Servosity/zammad

Zammad — Compétence pour Claude Code

Prérequis : Installer la CLI

Cette compétence utilise le binaire zammad-cli. Vous devez vérifier que la CLI est installée avant d'exécuter une commande de cette compétence. Si elle est manquante, installez-la d'abord :

1. macOS / Linux :

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

2. Windows (PowerShell) :

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

3. Vérifiez : zammad-cli --version
4. Assurez-vous que ~/.local/bin (macOS / Linux) ou %LOCALAPPDATA%\Programs\msp-skills (Windows) est dans le $PATH.

Le programme d'installation télécharge les binaires zammad-cli et zammad-mcp dans ~/.local/bin (macOS / Linux) ou %LOCALAPPDATA%\Programs\msp-skills (Windows). Il n'enregistre pas la compétence avec votre agent et n'écrit aucune configuration client MCP — consultez mcp-install.md pour cette connexion.

Si --version signale « commande introuvable » après l'installation, le runtime ne voit pas le répertoire des binaires dans le $PATH. Ne continuez pas avec les commandes de la compétence avant une vérification réussie.

Un binaire Go unique pour l'ensemble de l'interface REST de Zammad + la base de connaissances, avec un magasin SQLite hors ligne, une sortie structurée --json/--select et --dry-run sur chaque écriture. En plus de la parité, il ajoute une couche de gestion d'équipe calculée à partir de vos tickets synchronisés : agent-load et agent-trend pour la charge de travail, customer-health et churn-risk pour le risque client, overdue pour les arriérés, escalate pour le triage des sentiments et feedback pour l'analyse des demandes. Fonctionne avec toute instance Zammad — définissez l'URL de votre instance et votre jeton.

Quand utiliser cette CLI

Utilisez cette CLI lorsqu'un agent a besoin de lire, rechercher ou trier les tickets Zammad et le contenu de la base de connaissances, ou pour répondre à des questions de gestion d'équipe — qui est surchargé, quels clients sont à risque, ce qui vieillit, qui semble sur le point de se désabonner et quels thèmes de feedback se répètent. Elle est idéale pour l'automatisation du support, les réunions d'équipe et les revues de santé des comptes où la réponse nécessite une agrégation sur plusieurs tickets.

Anti-déclencheurs

N'utilisez pas cette CLI pour :

• N'utilisez pas cette CLI pour envoyer des e-mails marketing destinés aux clients — elle gère les articles de tickets, pas les campagnes.
• Ne l'utilisez pas pour configurer des déclencheurs, automations, SLA ou canaux Zammad — ce sont des fonctionnalités de la console d'administration qui ne sont pas exposées ici.
• Ne comptez pas sur escalade/risque de désabonnement/feedback comme analyse de sentiment faisant autorité — ce sont des heuristiques de mots-clés qui remontent des signaux à juger par un humain ou un agent.

Capacités uniques

Gestion d'équipe

• agent-load — Voir la charge actuelle de chaque agent, décomposée par état (ouvert/en attente/arriéré) afin d'équilibrer le travail avant qu'il ne s'accumule.

  Utilisez-le lorsqu'on demande qui est surchargé ou comment le travail est réparti dans l'équipe de support en ce moment.

  zammad-cli agent-load --json
  

• agent-trend — Afficher si la file d'attente de chaque agent croît ou diminue au cours des N dernières semaines, avec les écarts ouverts-fermés.

  Utilisez-le lorsqu'on demande si l'équipe suit le rythme ou prend du retard au fil du temps.

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

• customer-health — Classer les organisations par un signal de santé construit à partir du nombre d'ouvertures, de l'âge du plus ancien, du taux de réouverture, de la vélocité et de la dernière activité.

  Utilisez-le pour repérer les clients en difficulté avant qu'ils ne se plaignent.

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

• overdue — Trouver les tickets vieillissants encore en état nouveau/ouvert/en attente au-delà d'un seuil, pondérés par priorité pour que les pires remontent en haut.

  Utilisez-le pour attraper les tickets sur le point de violer un SLA ou de devenir obsolètes.

  zammad-cli overdue --days 3 --json
  

• escalate — Faire remonter les tickets actifs dont les messages récents des clients semblent mécontents (scan heuristique de signaux négatifs), classés par nombre de correspondances, ancienneté et priorité — avec les extraits correspondants affichés.

  Utilisez-le pour trouver les clients qui semblent en colère et qui devraient être escaladés ; il s'agit d'un triage par mots-clés avec extraits, donc vous prenez la décision finale.

  zammad-cli escalate --json
  

• churn-risk — Noter le risque de désabonnement de chaque organisation à partir des arriérés ouverts, des tickets en retard, des attentes sans réponse et des messages clients à sentiment négatif, en listant les facteurs contributeurs.

  Utilisez-le pour anticiper le désabonnement ; il fait remonter les facteurs afin que vous puissiez juger et agir.

  zammad-cli churn-risk --json
  

• feedback-scan — Classer le texte des tickets et articles dans les thèmes de demande de fonctionnalité, tarification, conformité et bug, avec les références des tickets sources et des extraits.

  Utilisez-le pour extraire ce que les clients demandent régulièrement concernant les fonctionnalités, la tarification et la conformité.

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

Base de connaissances

• kb browse — Afficher la base de connaissances sous forme d'arborescence catégorie/réponse analysée à partir du bundle d'initialisation.

  Utilisez-le pour voir la structure de la KB avant de lire ou de rechercher des réponses.

  zammad-cli kb browse
  

• kb search — Recherche textuelle dans les titres et les corps des réponses de la KB à partir du bundle d'initialisation KB en direct.

  Utilisez-le pour trouver la bonne réponse KB par mot-clé.

  zammad-cli kb search "restore" --json
  

• kb get — Résoudre un ID de réponse KB à partir du bundle d'initialisation pour obtenir son corps traduit complet.

  Utilisez-le pour lire le contenu complet d'une réponse KB.

  zammad-cli kb get 42
  

Ergonomie des tickets

• ticket note — Ajouter une note interne ou visible par le partenaire à un ticket en une ligne, avec les bonnes valeurs par défaut de type de contenu.

  Utilisez-le pour journaliser le travail sur un ticket sans construire manuellement la charge utile de l'article.

  zammad-cli ticket note 12345 --body "Investigations en cours, en attente des logs" --internal --dry-run
  

Webhooks (sans interrogation)

Zammad peut appeler cette machine lorsqu'un ticket est créé, mis à jour ou qu'un article est ajouté, afin que rien n'ait à interroger constamment.

# Une fois, avec un jeton possédant les permissions admin.webhook et admin.trigger
zammad-cli webhooks register --endpoint http://127.0.0.1:8789/zammad --yes
# Restez en cours d'exécution sur la machine à laquelle Zammad envoie les données
zammad-cli webhooks listen
# Lire ce qui est arrivé ; passer le curseur retourné comme --since la prochaine fois
zammad-cli events list --since 0 --json

• register crée un webhook Zammad et un déclencheur par événement (zammad.ticket.created, zammad.ticket.updated, zammad.article.created). Il génère le secret de signature et le stocke à côté de votre jeton API, lisible uniquement par vous ; ZAMMAD_WEBHOOK_SECRET le remplace. Le secret n'est jamais affiché : webhooks status montre seulement d'où il vient.
• listen se lie à cette machine uniquement (127.0.0.1, port 8789) par défaut et refuse de démarrer sans le secret. Chaque requête doit porter la X-Hub-Signature de Zammad, vérifiée avant la lecture du corps ; une livraison déjà vue est ignorée, et les corps de plus de 1 Mio sont refusés.
• Le webhook ne transporte que des IDs. L'écouteur récupère le ticket via l'API et enregistre l'événement, de sorte que le texte client ne transite jamais dans le webhook.
• Zammad abandonne une livraison après cinq tentatives sur environ deux minutes. Chaque fois que listen démarre, il enregistre d'abord ce qui a changé pendant son absence. Une livraison que Zammad abandonne alors que listen est en cours mais inaccessible (panne réseau) n'est pas enregistrée.
• Zammad doit pouvoir atteindre l'écouteur. Une instance Zammad auto-hébergée sur le même serveur fonctionne avec la configuration par défaut. Zammad sur une autre machine de votre réseau local nécessite listen --addr <lan-ip>:8789 --tls-cert <fichier> --tls-key <fichier> et un point de terminaison https://. Une instance Zammad Cloud ne peut pas atteindre une machine sur votre réseau local.
• Utilisez-le lorsque l'utilisateur souhaite réagir à des tickets nouveaux ou modifiés. Lisez avec events list --since <curseur> et conservez le curseur retourné ; exécutez tickets get <id> pour le texte d'un ticket.
• Via MCP, events_list lit les événements enregistrés (lecture seule, aucun appel à Zammad). webhooks_register et webhooks_unregister modifient Zammad uniquement avec confirm: true. listen est réservé à la CLI.

Référence des commandes

articles — Lire et ajouter des articles de ticket (notes et e-mails)

• zammad-cli articles by-ticket — Lister tous les articles d'un ticket
• zammad-cli articles create — Ajouter un article (note ou e-mail) à un ticket
• zammad-cli articles get — Obtenir un seul article par ID

groups — Groupes de routage de tickets

• zammad-cli groups get — Obtenir un groupe par ID
• zammad-cli groups list — Lister tous les groupes

kb — Catégories et réponses de la base de connaissances

• zammad-cli kb answer-create — Créer une réponse KB. Transmettez translations_attributes au format JSON, puis publiez ou marquez comme interne.
• zammad-cli kb answer-delete — Supprimer une réponse KB (nécessite la permission d'éditeur KB)
• zammad-cli kb answer-internal — Marquer une réponse KB comme interne (agent uniquement)
• zammad-cli kb answer-publish — Publier une réponse KB (la rendre publique)
• zammad-cli kb category-create — Créer une catégorie KB. Transmettez translations_attributes au format JSON.
• zammad-cli kb init — Récupérer le bundle complet de la base de connaissances (catégories, réponses, traductions). Utilisé par 'kb browse/search/get'.

organizations — Lire et gérer les organisations (clients / partenaires)

• zammad-cli organizations create — Créer une organisation
• zammad-cli organizations get — Obtenir une organisation par ID
• zammad-cli organizations list — Lister les organisations (paginé)
• zammad-cli organizations search — Rechercher des organisations par nom ou champ personnalisé
• zammad-cli organizations update — Mettre à jour une organisation

overviews — Vues d'ensemble des tickets pour les agents (vues sauvegardées)

• zammad-cli overviews get — Obtenir une vue d'ensemble (et ses tickets) par ID
• zammad-cli overviews list — Lister toutes les vues d'ensemble

priorities — Référence des priorités de ticket (mapper ID -> nom)

• zammad-cli priorities — Lister les priorités de ticket

states — Référence des états de ticket (mapper ID -> nom)

• zammad-cli states — Lister les états de ticket

tags — Tags de ticket

• zammad-cli tags add — Ajouter un tag à un objet
• zammad-cli tags all — Lister tous les tags définis dans l'instance (vocabulaire)
• zammad-cli tags list — Lister les tags sur un objet (par défaut un ticket)
• zammad-cli tags remove — Supprimer un tag d'un objet

tickets — Lire, rechercher, créer et modifier des tickets Zammad

• zammad-cli tickets create — Créer un ticket. Fournissez un titre, un groupe, un client et un article initial.
• zammad-cli tickets delete — Supprimer un ticket définitivement (nécessite la permission admin/suppression)
• zammad-cli tickets get — Obtenir un ticket par ID
• zammad-cli tickets list — Lister les tickets (paginé)
• zammad-cli tickets search — Rechercher des tickets avec la syntaxe de requête Zammad (par exemple 'state:open owner_id:3')
• zammad-cli tickets update — Mettre à jour un ticket (état, priorité, propriétaire, titre, organisation)

users — Lire et gérer les utilisateurs (agents et clients)

• zammad-cli users create — Créer un utilisateur
• zammad-cli users get — Obtenir un utilisateur par ID
• zammad-cli users list — Lister les utilisateurs (paginé)
• zammad-cli users me — Obtenir l'utilisateur authentifié (auto-vérification de l'authentification)
• zammad-cli users search — Rechercher des utilisateurs par e-mail, nom ou requête (par exemple organization_id:5)
• zammad-cli users update — Mettre à jour un utilisateur

agent-load

• zammad-cli agent-load — Voir la charge actuelle de chaque agent, décomposée par état (ouvert/en attente/arriéré) afin d'équilibrer le travail avant qu'il ne s'accumule.

agent-trend

• zammad-cli agent-trend — Afficher si la file d'attente de chaque agent croît ou diminue au cours des N dernières semaines, avec les écarts ouverts-fermés.

churn-risk

• zammad-cli churn-risk — Noter le risque de désabonnement de chaque organisation à partir des arriérés ouverts, des tickets en retard, des attentes sans réponse et des messages clients à sentiment négatif, en listant les facteurs contributeurs.

customer-health

• zammad-cli customer-health — Classer les organisations par un signal de santé construit à partir du nombre d'ouvertures, de l'âge du plus ancien, du taux de réouverture, de la vélocité et de la dernière activité.

escalate

• zammad-cli escalate — Faire remonter les tickets actifs dont les messages récents des clients semblent mécontents (scan heuristique de signaux négatifs), classés par nombre de correspondances, ancienneté et priorité — avec les extraits correspondants affichés.

feedback-scan

• zammad-cli feedback-scan — Classer le texte des tickets et articles dans les thèmes de demande de fonctionnalité, tarification, conformité et bug, avec les références des tickets sources et des extraits.

kb

• zammad-cli kb browse — Afficher la base de connaissances sous forme d'arborescence catégorie/réponse analysée à partir du bundle d'initialisation.
• zammad-cli kb search — Recherche textuelle dans les titres et les corps des réponses de la KB à partir du bundle d'initialisation KB en direct.
• zammad-cli kb get — Résoudre un ID de réponse KB à partir du bundle d'initialisation pour obtenir son corps traduit complet.

events

• zammad-cli events list — Lister les événements Zammad que webhooks listen a enregistrés après un curseur, du plus ancien au plus récent (local, aucun appel à Zammad).

webhooks

• zammad-cli webhooks register — Créer les webhooks et déclencheurs Zammad qui appellent webhooks listen (écrit uniquement avec --yes).
• zammad-cli webhooks listen — Recevoir, vérifier et enregistrer les webhooks Zammad jusqu'à l'arrêt (CLI uniquement).
• zammad-cli webhooks status — Afficher les webhooks et déclencheurs enregistrés ainsi que la provenance du secret (jamais le secret).
• zammad-cli webhooks unregister — Supprimer ce que webhooks register a créé (écrit uniquement avec --yes).

overdue

• zammad-cli overdue — Trouver les tickets vieillissants encore en état nouveau/ouvert/en attente au-delà d'un seuil, pondérés par priorité pour que les pires remontent en haut.

ticket

• zammad-cli ticket note — Ajouter une note interne ou visible par le partenaire à un ticket en une ligne, avec les bonnes valeurs par défaut de type de contenu.

Trouver la bonne commande

Lorsque vous savez ce que vous voulez faire mais pas quelle commande le fait, demandez directement à la CLI :

zammad-cli which "<capacité en vos propres mots>"

which résout une requête de capacité en langage naturel vers la commande la mieux adaptée depuis l'index de fonctionnalités organisé de cette CLI. Le code de sortie 0 signifie au moins une correspondance ; le code de sortie 2 signifie qu'aucune correspondance n'a été trouvée.

...

[truncé pour la traduction]