servosity/msp-skills/zammad

Zammad - Claude Code Skill

Prerequisites: Install the CLI

This skill drives the zammad-cli binary. You must verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:

1. macOS / Linux:

``bash bash <(curl -fsSL https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/zammad/install.sh) ``

1. Windows (PowerShell):

``powershell iwr -useb https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/zammad/install.ps1 | iex ``

1. Verify: zammad-cli --version
2. Ensure ~/.local/bin (macOS / Linux) or %LOCALAPPDATA%\Programs\msp-skills (Windows) is on $PATH.

The installer downloads the zammad-cli and zammad-mcp binaries into ~/.local/bin (macOS / Linux) or %LOCALAPPDATA%\Programs\msp-skills (Windows). It does not register the skill with your agent and writes no MCP client config - see mcp-install.md for that wire-up.

If --version reports "command not found" after install, the runtime cannot see the binary directory on $PATH. Do not proceed with skill commands until verification succeeds.

A single Go binary for the whole Zammad REST + Knowledge Base surface with an offline SQLite store, structured --json/--select output, and --dry-run on every write. On top of parity it adds a team-management layer computed from your synced tickets: agent-load and agent-trend for workload, customer-health and churn-risk for account risk, overdue for aging backlog, escalate for sentiment triage, and feedback for mining what customers ask for. Works against any Zammad instance - set your instance URL and token.

When to Use This CLI

Use this CLI when an agent needs to read, search, or triage Zammad tickets and Knowledge Base content, or to answer team-management questions - who is overloaded, which customers are at risk, what is aging, who sounds like they might churn, and what feedback themes are recurring. It is ideal for support-ops automation, standups, and account-health reviews where the answer requires aggregating across many tickets.

Anti-triggers

Do not use this CLI for:

• Do not use this CLI to send customer-facing marketing email - it manages ticket articles, not campaigns.
• Do not use it to configure Zammad triggers, automations, SLAs, or channels - those are admin-console features not exposed here.
• Do not rely on escalate/churn/feedback as authoritative sentiment analysis - they are heuristic keyword triage that surface signals for a human or agent to judge.

Unique Capabilities

Team management

• `agent-load` - See each agent's current ticket load broken out by state (open/pending/backlog) so you can balance work before it piles up.

_Reach for this when asked who is overloaded or how work is distributed across the support team right now._

``bash zammad-cli agent-load --json ``

• `agent-trend` - Show whether each agent's queue is growing or shrinking across the last N weeks, with opened-vs-closed deltas.

_Reach for this when asked if the team is keeping up or falling behind over time._

``bash zammad-cli agent-trend --weeks 2 --json ``

• `customer-health` - Rank organizations by a health signal built from open count, oldest-open age, reopen rate, velocity, and last activity.

_Reach for this to spot which customers are struggling before they complain._

``bash zammad-cli customer-health --at-risk --json ``

• `overdue` - Find aging tickets still in new/open/pending past a threshold, weighted by priority so the worst rise to the top.

_Reach for this to catch tickets about to breach SLA or go stale._

``bash zammad-cli overdue --days 3 --json ``

• `escalate` - Surface active tickets whose recent customer messages read as upset (heuristic negative-signal scan), ranked by hits, age, and priority - with the matched snippets shown.

_Reach for this to find customers who sound angry and should be escalated; it is keyword triage with snippets, so you make the final call._

``bash zammad-cli escalate --json ``

• `churn-risk` - Score each organization's churn risk from open backlog, overdue tickets, unanswered pending, and negative-sentiment customer messages, listing the contributing factors.

_Reach for this to get ahead of churn; it surfaces the factors so you can judge and act._

``bash zammad-cli churn-risk --json ``

• `feedback-scan` - Bucket ticket and article text into feature-request, pricing, compliance, and bug themes with the source ticket refs and snippets.

_Reach for this to mine what customers keep asking for across features, pricing, and compliance._

``bash zammad-cli feedback-scan --bucket pricing --json ``

Knowledge Base

• `kb browse` - Print the Knowledge Base as a category/answer tree parsed from the init bundle.

_Reach for this to see the KB structure before reading or searching answers._

``bash zammad-cli kb browse ``

• `kb search` - Text search over KB answer titles and bodies from the live KB init bundle.

_Reach for this to find the right KB answer by keyword._

``bash zammad-cli kb search "restore" --json ``

• `kb get` - Resolve a KB answer id from the init bundle to its full translated body.

_Reach for this to read a KB answer's full content._

``bash zammad-cli kb get 42 ``

Ticket ergonomics

• `ticket note` - Add an internal or partner-visible note to a ticket in one line, with correct content-type defaults.

_Reach for this to log work on a ticket without hand-building the article payload._

``bash zammad-cli ticket note 12345 --body "Investigated, awaiting logs" --internal --dry-run ``

Webhooks (no polling)

Zammad can call this machine when a ticket is created or updated or an article is added, so nothing has to poll it.

# Once, with a token that has the admin.webhook and admin.trigger permissions
zammad-cli webhooks register --endpoint http://127.0.0.1:8789/zammad --yes
# Keep running on the machine Zammad posts to
zammad-cli webhooks listen
# Read what arrived; pass the returned cursor as --since next time
zammad-cli events list --since 0 --json

• register creates one Zammad webhook and one trigger per event (zammad.ticket.created, zammad.ticket.updated, zammad.article.created). It generates the signature secret and stores it beside your API token, readable only by you; ZAMMAD_WEBHOOK_SECRET overrides it. The secret is never printed: webhooks status shows only where it comes from.
• listen binds to this machine only (127.0.0.1, port 8789) by default and refuses to start without the secret. Every request must carry Zammad's X-Hub-Signature, checked before the body is read; a delivery it has already seen is dropped, and bodies over 1 MiB are refused.
• The webhook carries IDs only. The listener fetches the ticket through the API and records the event, so customer text never travels in the webhook.
• Zammad gives up on a delivery after five attempts over about two minutes. Each time listen starts, it first records what changed while it was down. A delivery Zammad gives up on while listen is running but cannot be reached (a network outage) is not recorded.
• Zammad has to reach the listener. A self-hosted Zammad on the same server works with the default. Zammad on another machine on your LAN needs listen --addr <lan-ip>:8789 --tls-cert <file> --tls-key <file> and an https:// endpoint. A Zammad Cloud instance cannot reach a machine on your LAN.
• Reach for this when the user wants to react to new or changed tickets. Read with events list --since <cursor> and keep the returned cursor; run tickets get <id> for a ticket's text.
• Over MCP, events_list reads the recorded events (read-only, no Zammad call). webhooks_register and webhooks_unregister change Zammad only with confirm: true. listen is CLI-only.

Command Reference

articles - Read and add ticket articles (notes and emails)

• zammad-cli articles by-ticket - List all articles for a ticket
• zammad-cli articles create - Add an article (note or email) to a ticket
• zammad-cli articles get - Get a single article by id

groups - Ticket routing groups

• zammad-cli groups get - Get a group by id
• zammad-cli groups list - List all groups

kb - Knowledge Base categories and answers

• zammad-cli kb answer-create - Create a KB answer. Pass translations_attributes as JSON, then publish or mark internal.
• zammad-cli kb answer-delete - Delete a KB answer (requires KB editor permission)
• zammad-cli kb answer-internal - Mark a KB answer internal (agent-only)
• zammad-cli kb answer-publish - Publish a KB answer (make it public)
• zammad-cli kb category-create - Create a KB category. Pass translations_attributes as JSON.
• zammad-cli kb init - Fetch the full Knowledge Base bundle (categories, answers, translations). Used by 'kb browse/search/get'.

organizations - Read and manage organizations (customers / partners)

• zammad-cli organizations create - Create an organization
• zammad-cli organizations get - Get an organization by id
• zammad-cli organizations list - List organizations (paginated)
• zammad-cli organizations search - Search organizations by name or custom field
• zammad-cli organizations update - Update an organization

overviews - Agent ticket overviews (saved views)

• zammad-cli overviews get - Get an overview (and its tickets) by id
• zammad-cli overviews list - List all overviews

priorities - Ticket priority reference (id -> name map)

• zammad-cli priorities - List ticket priorities

states - Ticket state reference (id -> name map)

• zammad-cli states - List ticket states

tags - Ticket tags

• zammad-cli tags add - Add a tag to an object
• zammad-cli tags all - List every tag defined in the instance (vocabulary)
• zammad-cli tags list - List tags on an object (defaults to a ticket)
• zammad-cli tags remove - Remove a tag from an object

tickets - Read, search, create, and change Zammad tickets

• zammad-cli tickets create - Create a ticket. Provide title, group, a customer, and an initial article.
• zammad-cli tickets delete - Delete a ticket permanently (requires admin / delete permission)
• zammad-cli tickets get - Get a ticket by id
• zammad-cli tickets list - List tickets (paginated)
• zammad-cli tickets search - Search tickets with Zammad query syntax (e.g. 'state:open owner_id:3')
• zammad-cli tickets update - Update a ticket (state, priority, owner, title, organization)

users - Read and manage users (agents and customers)

• zammad-cli users create - Create a user
• zammad-cli users get - Get a user by id
• zammad-cli users list - List users (paginated)
• zammad-cli users me - Get the authenticated user (auth self-check)
• zammad-cli users search - Search users by email, name, or query (e.g. organization_id:5)
• zammad-cli users update - Update a user

agent-load

• zammad-cli agent-load - See each agent's current ticket load broken out by state (open/pending/backlog) so you can balance work before it piles up.

agent-trend

• zammad-cli agent-trend - Show whether each agent's queue is growing or shrinking across the last N weeks, with opened-vs-closed deltas.

churn-risk

• zammad-cli churn-risk - Score each organization's churn risk from open backlog, overdue tickets, unanswered pending, and negative-sentiment customer messages, listing the contributing factors.

customer-health

• zammad-cli customer-health - Rank organizations by a health signal built from open count, oldest-open age, reopen rate, velocity, and last activity.

escalate