Servosity/zammad

Zammad - Skill para Claude Code

Pré-requisitos: Instalar o CLI

Este skill utiliza o binário zammad-cli. Você deve verificar se o CLI está instalado antes de invocar qualquer comando deste skill. Se estiver faltando, instale-o primeiro:

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. Verifique: zammad-cli --version
4. Certifique-se de que ~/.local/bin (macOS / Linux) ou %LOCALAPPDATA%\Programs\msp-skills (Windows) está no $PATH.

O instalador baixa os binários zammad-cli e zammad-mcp para ~/.local/bin (macOS / Linux) ou %LOCALAPPDATA%\Programs\msp-skills (Windows). Ele não registra o skill com seu agente e não escreve nenhuma configuração de cliente MPC - veja mcp-install.md para essa conexão.

Se --version relatar "comando não encontrado" após a instalação, o runtime não consegue ver o diretório do binário no $PATH. Não prossiga com os comandos do skill até que a verificação seja bem-sucedida.

Um único binário Go para toda a superfície REST + Base de Conhecimento do Zammad com um armazenamento SQLite offline, saída estruturada --json/--select e --dry-run em toda escrita. Além da paridade, ele adiciona uma camada de gestão de equipe computada a partir dos seus tickets sincronizados: agent-load e agent-trend para carga de trabalho, customer-health e churn-risk para risco de conta, overdue para backlog envelhecido, escalate para triagem de sentimento e feedback para mineração do que os clientes pedem. Funciona com qualquer instância do Zammad - defina a URL da sua instância e o token.

Quando Usar Este CLI

Use este CLI quando um agente precisar ler, pesquisar ou fazer triagem de tickets do Zammad e conteúdo da Base de Conhecimento, ou para responder a perguntas de gestão de equipe - quem está sobrecarregado, quais clientes estão em risco, o que está envelhecendo, quem parece que pode cancelar, e quais temas de feedback são recorrentes. É ideal para automação de operações de suporte, standups e revisões de saúde de conta onde a resposta requer agregação de muitos tickets.

Antigatilhos

Não use este CLI para:

• Não use este CLI para enviar e-mails de marketing voltados ao cliente - ele gerencia artigos de tickets, não campanhas.
• Não use para configurar gatilhos, automações, SLAs ou canais do Zammad - esses são recursos do console de administração não expostos aqui.
• Não confie em escalate/churn/feedback como análise de sentimento autoritativa - eles são triagens heurísticas de palavras-chave que sinalizam para um humano ou agente julgar.

Capacidades Únicas

Gestão de Equipe

• agent-load - Veja a carga atual de tickets de cada agente dividida por estado (aberto/pendente/backlog) para que você possa equilibrar o trabalho antes que ele se acumule.

  Use isto quando perguntado quem está sobrecarregado ou como o trabalho está distribuído na equipe de suporte agora.

  zammad-cli agent-load --json
  

• agent-trend - Mostre se a fila de cada agente está crescendo ou diminuindo nas últimas N semanas, com deltas de abertos vs fechados.

  Use isto quando perguntado se a equipe está acompanhando ou ficando para trás ao longo do tempo.

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

• customer-health - Classifique organizações por um sinal de saúde construído a partir de contagem de abertos, idade do mais antigo aberto, taxa de reabertura, velocidade e última atividade.

  Use isto para identificar quais clientes estão com dificuldades antes que reclamem.

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

• overdue - Encontre tickets envelhecidos ainda em novo/aberto/pendente além de um limite, ponderados por prioridade para que os piores subam ao topo.

  Use isto para capturar tickets prestes a violar SLA ou ficarem obsoletos.

  zammad-cli overdue --days 3 --json
  

• escalate - Superficie tickets ativos cujas mensagens recentes do cliente parecem irritadas (varredura heurística de sinal negativo), classificados por acertos, idade e prioridade - com os trechos correspondentes mostrados.

  Use isto para encontrar clientes que parecem irritados e devem ser escalados; é triagem de palavras-chave com trechos, então você faz a decisão final.

  zammad-cli escalate --json
  

• churn-risk - Pontue o risco de churn de cada organização a partir de backlog aberto, tickets vencidos, pendentes não respondidos e mensagens de cliente com sentimento negativo, listando os fatores contribuintes.

  Use isto para se antecipar ao churn; ele superficializa os fatores para que você possa julgar e agir.

  zammad-cli churn-risk --json
  

• feedback-scan - Agrupe texto de tickets e artigos nos temas solicitação de funcionalidade, preço, conformidade e bug com as referências e trechos dos tickets de origem.

  Use isto para minerar o que os clientes continuam pedindo em relação a funcionalidades, preços e conformidade.

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

Base de Conhecimento

• kb browse - Imprima a Base de Conhecimento como uma árvore de categoria/resposta analisada a partir do pacote de inicialização.

  Use isto para ver a estrutura da KB antes de ler ou pesquisar respostas.

  zammad-cli kb browse
  

• kb search - Pesquisa textual sobre títulos e corpos de respostas da KB a partir do pacote de inicialização da KB ativa.

  Use isto para encontrar a resposta correta da KB por palavra-chave.

  zammad-cli kb search "restore" --json
  

• kb get - Resolva um ID de resposta da KB a partir do pacote de inicialização para seu corpo completo traduzido.

  Use isto para ler o conteúdo completo de uma resposta da KB.

  zammad-cli kb get 42
  

Ergonomia de Tickets

• ticket note - Adicione uma nota interna ou visível ao parceiro a um ticket em uma linha, com padrões corretos de tipo de conteúdo.

  Use isto para registrar trabalho em um ticket sem construir manualmente o payload do artigo.

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

Webhooks (sem polling)

O Zammad pode chamar esta máquina quando um ticket é criado ou atualizado ou um artigo é adicionado, para que nada precise fazer polling.

# Uma vez, com um token que tenha as permissões admin.webhook e admin.trigger
zammad-cli webhooks register --endpoint http://127.0.0.1:8789/zammad --yes
# Mantenha em execução na máquina para a qual o Zammad publica
zammad-cli webhooks listen
# Leia o que chegou; passe o cursor retornado como --since da próxima vez
zammad-cli events list --since 0 --json

• register cria um webhook no Zammad e um gatilho por evento (zammad.ticket.created, zammad.ticket.updated, zammad.article.created). Ele gera o segredo da assinatura e o armazena ao lado do seu token de API, legível apenas por você; ZAMMAD_WEBHOOK_SECRET o substitui. O segredo nunca é impresso: webhooks status mostra apenas de onde ele vem.
• listen vincula-se apenas a esta máquina (127.0.0.1, porta 8789) por padrão e se recusa a iniciar sem o segredo. Cada requisição deve carregar o X-Hub-Signature do Zammad, verificado antes que o corpo seja lido; uma entrega já vista é descartada e corpos acima de 1 MiB são recusados.
• O webhook carrega apenas IDs. O listener busca o ticket através da API e registra o evento, para que o texto do cliente nunca viaje no webhook.
• O Zammad desiste de uma entrega após cinco tentativas em cerca de dois minutos. Cada vez que listen inicia, ele primeiro registra o que mudou enquanto estava inativo. Uma entrega da qual o Zammad desiste enquanto listen está em execução, mas não pode ser alcançado (uma falha de rede), não é registrada.
• O Zammad precisa alcançar o listener. Um Zammad auto-hospedado no mesmo servidor funciona com o padrão. O Zammad em outra máquina na sua LAN precisa de listen --addr <lan-ip>:8789 --tls-cert <file> --tls-key <file> e um endpoint https://. Uma instância do Zammad Cloud não consegue alcançar uma máquina na sua LAN.
• Use isto quando o usuário quiser reagir a tickets novos ou alterados. Leia com events list --since <cursor> e mantenha o cursor retornado; execute tickets get <id> para o texto de um ticket.
• Via MCP, events_list lê os eventos registrados (somente leitura, sem chamada ao Zammad). webhooks_register e webhooks_unregister alteram o Zammad apenas com confirm: true. listen é apenas CLI.

Referência de Comandos

articles - Leia e adicione artigos de ticket (notas e e-mails)

• zammad-cli articles by-ticket - Liste todos os artigos de um ticket
• zammad-cli articles create - Adicione um artigo (nota ou e-mail) a um ticket
• zammad-cli articles get - Obtenha um único artigo por id

groups - Grupos de roteamento de tickets

• zammad-cli groups get - Obtenha um grupo por id
• zammad-cli groups list - Liste todos os grupos

kb - Categorias e respostas da Base de Conhecimento

• zammad-cli kb answer-create - Crie uma resposta KB. Passe translations_attributes como JSON, depois publique ou marque como interna.
• zammad-cli kb answer-delete - Exclua uma resposta KB (requer permissão de editor KB)
• zammad-cli kb answer-internal - Marque uma resposta KB como interna (apenas agente)
• zammad-cli kb answer-publish - Publique uma resposta KB (torne-a pública)
• zammad-cli kb category-create - Crie uma categoria KB. Passe translations_attributes como JSON.
• zammad-cli kb init - Busque o pacote completo da Base de Conhecimento (categorias, respostas, traduções). Usado por 'kb browse/search/get'.

organizations - Leia e gerencie organizações (clientes / parceiros)

• zammad-cli organizations create - Crie uma organização
• zammad-cli organizations get - Obtenha uma organização por id
• zammad-cli organizations list - Liste organizações (paginado)
• zammad-cli organizations search - Pesquise organizações por nome ou campo personalizado
• zammad-cli organizations update - Atualize uma organização

overviews - Visões gerais de tickets do agente (visualizações salvas)

• zammad-cli overviews get - Obtenha uma visão geral (e seus tickets) por id
• zammad-cli overviews list - Liste todas as visões gerais

priorities - Referência de prioridade de ticket (mapa id -> nome)

• zammad-cli priorities - Liste as prioridades de ticket

states - Referência de estado de ticket (mapa id -> nome)

• zammad-cli states - Liste os estados de ticket

tags - Tags de ticket

• zammad-cli tags add - Adicione uma tag a um objeto
• zammad-cli tags all - Liste cada tag definida na instância (vocabulário)
• zammad-cli tags list - Liste tags em um objeto (padrão é um ticket)
• zammad-cli tags remove - Remova uma tag de um objeto

tickets - Leia, pesquise, crie e altere tickets do Zammad

• zammad-cli tickets create - Crie um ticket. Forneça título, grupo, um cliente e um artigo inicial.
• zammad-cli tickets delete - Exclua um ticket permanentemente (requer admin / permissão de exclusão)
• zammad-cli tickets get - Obtenha um ticket por id
• zammad-cli tickets list - Liste tickets (paginado)
• zammad-cli tickets search - Pesquise tickets com a sintaxe de consulta do Zammad (ex.: 'state:open owner_id:3')
• zammad-cli tickets update - Atualize um ticket (estado, prioridade, proprietário, título, organização)

users - Leia e gerencie usuários (agentes e clientes)

• zammad-cli users create - Crie um usuário
• zammad-cli users get - Obtenha um usuário por id
• zammad-cli users list - Liste usuários (paginado)
• zammad-cli users me - Obtenha o usuário autenticado (auto-verificação de autenticação)
• zammad-cli users search - Pesquise usuários por email, nome ou consulta (ex.: organization_id:5)
• zammad-cli users update - Atualize um usuário

agent-load

• zammad-cli agent-load - Veja a carga atual de tickets de cada agente dividida por estado (aberto/pendente/backlog) para que você possa equilibrar o trabalho antes que ele se acumule.

agent-trend

• zammad-cli agent-trend - Mostre se a fila de cada agente está crescendo ou diminuindo nas últimas N semanas, com deltas de abertos vs fechados.

churn-risk

• zammad-cli churn-risk - Pontue o risco de churn de cada organização a partir de backlog aberto, tickets vencidos, pendentes não respondidos e mensagens de cliente com sentimento negativo, listando os fatores contribuintes.

customer-health

• zammad-cli customer-health - Classifique organizações por um sinal de saúde construído a partir de contagem de abertos, idade do mais antigo aberto, taxa de reabertura, velocidade e última atividade.

escalate

• zammad-cli escalate - Superficie tickets ativos cujas mensagens recentes do cliente parecem irritadas (varredura heurística de sinal negativo), classificados por acertos, idade e prioridade - com os trechos correspondentes mostrados.

feedback-scan

• zammad-cli feedback-scan - Agrupe texto de tickets e artigos nos temas solicitação de funcionalidade, preço, conformidade e bug com as referências e trechos dos tickets de origem.

kb

• zammad-cli kb browse - Imprima a Base de Conhecimento como uma árvore de categoria/resposta analisada a partir do pacote de inicialização.
• zammad-cli kb search - Pesquisa textual sobre títulos e corpos de respostas da KB a partir do pacote de inicialização da KB ativa.
• zammad-cli kb get - Resolva um ID de resposta da KB a partir do pacote de inicialização para seu corpo completo traduzido.

events

• zammad-cli events list - Liste os eventos do Zammad que webhooks listen registrou após um cursor, do mais antigo primeiro (local, sem chamada ao Zammad).

webhooks

• zammad-cli webhooks register - Crie os webhooks e gatilhos do Zammad que chamam webhooks listen (escreve apenas com --yes).
• zammad-cli webhooks listen - Receba, verifique e registre webhooks do Zammad até ser interrompido (apenas CLI).
• zammad-cli webhooks status - Mostre os webhooks e gatilhos registrados e de onde o segredo vem (nunca o segredo).
• zammad-cli webhooks unregister - Remova o que webhooks register criou (escreve apenas com --yes).

overdue

• zammad-cli overdue - Encontre tickets envelhecidos ainda em novo/aberto/pendente além de um limite, ponderados por prioridade para que os piores subam ao topo.

ticket

• zammad-cli ticket note - Adicione uma nota interna ou visível ao parceiro a um ticket em uma linha, com padrões corretos de tipo de conteúdo.

Encontrando o Comando Certo

Quando você sabe o que quer fazer, mas não qual comando faz isso, pergunte diretamente ao CLI:

zammad-cli which "<capacidade em suas próprias palavras>"

which resolve uma consulta de capacidade em linguagem natural para o melhor comando correspondente a partir do índice de recursos selecionados deste CLI. Código de saída 0 significa pelo menos uma correspondência; código de saída 2 significa nenhuma correspondência confiante.