Servosity/zammad

Zammad - Skill para Claude Code

Requisitos previos: Instalar el CLI

Este skill utiliza el binario zammad-cli. Debes verificar que el CLI esté instalado antes de invocar cualquier comando de este skill. Si falta, instálalo primero:

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. Verifica: zammad-cli --version
4. Asegúrate de que ~/.local/bin (macOS / Linux) o %LOCALAPPDATA%\Programs\msp-skills (Windows) esté en $PATH.

El instalador descarga los binarios zammad-cli y zammad-mcp en ~/.local/bin (macOS / Linux) o %LOCALAPPDATA%\Programs\msp-skills (Windows). No registra el skill con tu agente ni escribe ninguna configuración de cliente MCP; consulta mcp-install.md para esa configuración.

Si --version reporta "comando no encontrado" después de la instalación, el runtime no puede ver el directorio del binario en $PATH. No continúes con los comandos del skill hasta que la verificación sea exitosa.

Un solo binario Go para toda la superficie REST + Base de Conocimiento de Zammad con un almacén SQLite offline, salida estructurada --json/--select, y --dry-run en cada escritura. Sobre la paridad, añade una capa de gestión de equipo calculada a partir de tus tickets sincronizados: agent-load y agent-trend para carga de trabajo, customer-health y churn-risk para riesgo de cuenta, overdue para backlog envejecido, escalate para triaje de sentimiento, y feedback para extraer lo que los clientes piden. Funciona contra cualquier instancia de Zammad: configura la URL de tu instancia y el token.

Cuándo usar este CLI

Usa este CLI cuando un agente necesita leer, buscar o triar tickets de Zammad y contenido de la base de conocimiento, o para responder preguntas de gestión de equipo: quién está sobrecargado, qué clientes están en riesgo, qué está envejeciendo, quién parece que podría abandonar y qué temas de retroalimentación son recurrentes. Es ideal para automatización de operaciones de soporte, reuniones diarias y revisiones de salud de cuentas donde la respuesta requiere agregar datos de muchos tickets.

Antigatillos

No uses este CLI para:

• No uses este CLI para enviar correos electrónicos de marketing a clientes: gestiona artículos de tickets, no campañas.
• No lo uses para configurar activadores, automatizaciones, SLA o canales de Zammad: esas son características de la consola de administración no expuestas aquí.
• No confíes en escalate/churn/feedback como análisis de sentimiento autorizado: son triaje heurístico de palabras clave que señalan indicios para que un humano o agente juzgue.

Capacidades únicas

Gestión de equipo

• agent-load - Muestra la carga actual de tickets de cada agente desglosada por estado (abierto/pendiente/en backlog) para que puedas equilibrar el trabajo antes de que se acumule.

  Úsalo cuando te pregunten quién está sobrecargado o cómo está distribuido el trabajo en el equipo de soporte ahora mismo.

  zammad-cli agent-load --json
  

• agent-trend - Muestra si la cola de cada agente está creciendo o reduciéndose en las últimas N semanas, con deltas de abiertos vs. cerrados.

  Úsalo cuando te pregunten si el equipo está al día o se está quedando atrás con el tiempo.

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

• customer-health - Clasifica las organizaciones por una señal de salud construida a partir del recuento de abiertos, antigüedad del más antiguo, tasa de reapertura, velocidad y última actividad.

  Úsalo para detectar qué clientes están teniendo dificultades antes de que se quejen.

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

• overdue - Encuentra tickets que envejecen y aún están en nuevo/abierto/pendiente más allá de un umbral, ponderados por prioridad para que los peores suban a la cima.

  Úsalo para detectar tickets a punto de incumplir SLA o volverse obsoletos.

  zammad-cli overdue --days 3 --json
  

• escalate - Muestra los tickets activos cuyos mensajes recientes de clientes indican enojo (exploración heurística de señales negativas), clasificados por aciertos, antigüedad y prioridad, con los fragmentos coincidentes mostrados.

  Úsalo para encontrar clientes que suenan enfadados y deben ser escalados; es un triaje por palabras clave con fragmentos, así que tú tomas la decisión final.

  zammad-cli escalate --json
  

• churn-risk - Puntúa el riesgo de abandono de cada organización según el backlog abierto, tickets vencidos, pendientes sin respuesta y mensajes de clientes con sentimiento negativo, enumerando los factores contribuyentes.

  Úsalo para adelantarte al abandono; muestra los factores para que puedas juzgar y actuar.

  zammad-cli churn-risk --json
  

• feedback-scan - Agrupa el texto de tickets y artículos en temas de solicitud de funcionalidad, precios, cumplimiento y errores, con las referencias y fragmentos de los tickets fuente.

  Úsalo para extraer lo que los clientes siguen pidiendo en cuanto a funcionalidades, precios y cumplimiento.

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

Base de conocimiento

• kb browse - Imprime la base de conocimiento como un árbol de categorías/respuestas analizado desde el paquete de inicio.

  Úsalo para ver la estructura de la KB antes de leer o buscar respuestas.

  zammad-cli kb browse
  

• kb search - Búsqueda de texto en títulos y cuerpos de respuestas de la KB desde el paquete de inicio en vivo.

  Úsalo para encontrar la respuesta correcta de la KB por palabra clave.

  zammad-cli kb search "restore" --json
  

• kb get - Resuelve un ID de respuesta de la KB desde el paquete de inicio a su cuerpo traducido completo.

  Úsalo para leer el contenido completo de una respuesta de la KB.

  zammad-cli kb get 42
  

Ergonomía de tickets

• ticket note - Añade una nota interna o visible para el socio a un ticket en una línea, con valores predeterminados correctos de tipo de contenido.

  Úsalo para registrar trabajo en un ticket sin construir manualmente el payload del artículo.

  zammad-cli ticket note 12345 --body "Investigado, esperando registros" --internal --dry-run
  

Webhooks (sin polling)

Zammad puede llamar a esta máquina cuando se crea o actualiza un ticket o se añade un artículo, para que no haya que hacer polling.

# Una vez, con un token que tenga los permisos admin.webhook y admin.trigger
zammad-cli webhooks register --endpoint http://127.0.0.1:8789/zammad --yes
# Mantener ejecutándose en la máquina a la que Zammad publica
zammad-cli webhooks listen
# Leer lo que llegó; pasar el cursor devuelto como --since la próxima vez
zammad-cli events list --since 0 --json

• register crea un webhook y un activador de Zammad por evento (zammad.ticket.created, zammad.ticket.updated, zammad.article.created). Genera el secreto de firma y lo almacena junto a tu token de API, legible solo por ti; ZAMMAD_WEBHOOK_SECRET lo sobrescribe. El secreto nunca se imprime: webhooks status muestra solo de dónde viene.
• listen se vincula solo a esta máquina (127.0.0.1, puerto 8789) por defecto y se niega a iniciar sin el secreto. Cada solicitud debe llevar la X-Hub-Signature de Zammad, verificada antes de leer el cuerpo; una entrega ya vista se descarta y los cuerpos de más de 1 MiB se rechazan.
• El webhook lleva solo IDs. El oyente obtiene el ticket a través de la API y registra el evento, por lo que el texto del cliente nunca viaja en el webhook.
• Zammad abandona una entrega después de cinco intentos en aproximadamente dos minutos. Cada vez que listen se inicia, primero registra lo que cambió mientras estaba caído. Una entrega que Zammad abandona mientras listen está ejecutándose pero no puede ser alcanzado (una caída de red) no se registra.
• Zammad debe poder alcanzar al oyente. Un Zammad autoalojado en el mismo servidor funciona con la configuración predeterminada. Zammad en otra máquina de tu LAN necesita listen --addr <lan-ip>:8789 --tls-cert <file> --tls-key <file> y un endpoint https://. Una instancia de Zammad Cloud no puede alcanzar una máquina en tu LAN.
• Úsalo cuando el usuario quiera reaccionar a tickets nuevos o modificados. Lee con events list --since <cursor> y guarda el cursor devuelto; ejecuta tickets get <id> para el texto de un ticket.
• En MCP, events_list lee los eventos registrados (solo lectura, sin llamada a Zammad). webhooks_register y webhooks_unregister cambian Zammad solo con confirm: true. listen es solo CLI.

Referencia de comandos

articles - Leer y añadir artículos de tickets (notas y correos)

• zammad-cli articles by-ticket - Listar todos los artículos de un ticket
• zammad-cli articles create - Añadir un artículo (nota o correo) a un ticket
• zammad-cli articles get - Obtener un artículo por ID

groups - Grupos de enrutamiento de tickets

• zammad-cli groups get - Obtener un grupo por ID
• zammad-cli groups list - Listar todos los grupos

kb - Categorías y respuestas de la base de conocimiento

• zammad-cli kb answer-create - Crear una respuesta de KB. Pasa translations_attributes como JSON, luego publica o marca como interna.
• zammad-cli kb answer-delete - Eliminar una respuesta de KB (requiere permiso de editor de KB)
• zammad-cli kb answer-internal - Marcar una respuesta de KB como interna (solo agentes)
• zammad-cli kb answer-publish - Publicar una respuesta de KB (hacerla pública)
• zammad-cli kb category-create - Crear una categoría de KB. Pasa translations_attributes como JSON.
• zammad-cli kb init - Obtener el paquete completo de la base de conocimiento (categorías, respuestas, traducciones). Usado por 'kb browse/search/get'.

organizations - Leer y gestionar organizaciones (clientes/socios)

• zammad-cli organizations create - Crear una organización
• zammad-cli organizations get - Obtener una organización por ID
• zammad-cli organizations list - Listar organizaciones (paginado)
• zammad-cli organizations search - Buscar organizaciones por nombre o campo personalizado
• zammad-cli organizations update - Actualizar una organización

overviews - Vistas generales de tickets del agente (vistas guardadas)

• zammad-cli overviews get - Obtener una vista general (y sus tickets) por ID
• zammad-cli overviews list - Listar todas las vistas generales

priorities - Referencia de prioridades de tickets (mapa ID -> nombre)

• zammad-cli priorities - Listar prioridades de tickets

states - Referencia de estados de tickets (mapa ID -> nombre)

• zammad-cli states - Listar estados de tickets

tags - Etiquetas de tickets

• zammad-cli tags add - Añadir una etiqueta a un objeto
• zammad-cli tags all - Listar cada etiqueta definida en la instancia (vocabulario)
• zammad-cli tags list - Listar etiquetas en un objeto (por defecto un ticket)
• zammad-cli tags remove - Eliminar una etiqueta de un objeto

tickets - Leer, buscar, crear y cambiar tickets de Zammad

• zammad-cli tickets create - Crear un ticket. Proporciona título, grupo, un cliente y un artículo inicial.
• zammad-cli tickets delete - Eliminar un ticket permanentemente (requiere permiso de administrador/eliminación)
• zammad-cli tickets get - Obtener un ticket por ID
• zammad-cli tickets list - Listar tickets (paginado)
• zammad-cli tickets search - Buscar tickets con la sintaxis de consulta de Zammad (ej. 'state:open owner_id:3')
• zammad-cli tickets update - Actualizar un ticket (estado, prioridad, propietario, título, organización)

users - Leer y gestionar usuarios (agentes y clientes)

• zammad-cli users create - Crear un usuario
• zammad-cli users get - Obtener un usuario por ID
• zammad-cli users list - Listar usuarios (paginado)
• zammad-cli users me - Obtener el usuario autenticado (autocomprobación de autenticación)
• zammad-cli users search - Buscar usuarios por correo electrónico, nombre o consulta (ej. organization_id:5)
• zammad-cli users update - Actualizar un usuario

agent-load

• zammad-cli agent-load - Ver la carga actual de tickets de cada agente desglosada por estado (abierto/pendiente/en backlog) para equilibrar el trabajo antes de que se acumule.

agent-trend

• zammad-cli agent-trend - Mostrar si la cola de cada agente está creciendo o reduciéndose en las últimas N semanas, con deltas de abiertos vs. cerrados.

churn-risk

• zammad-cli churn-risk - Puntuar el riesgo de abandono de cada organización según el backlog abierto, tickets vencidos, pendientes sin respuesta y mensajes de clientes con sentimiento negativo, enumerando los factores contribuyentes.

customer-health

• zammad-cli customer-health - Clasificar las organizaciones por una señal de salud construida a partir del recuento de abiertos, antigüedad del más antiguo, tasa de reapertura, velocidad y última actividad.

escalate

• zammad-cli escalate - Mostrar los tickets activos cuyos mensajes recientes de clientes indican enojo (exploración heurística de señales negativas), clasificados por aciertos, antigüedad y prioridad, con los fragmentos coincidentes mostrados.

feedback-scan

• zammad-cli feedback-scan - Agrupar el texto de tickets y artículos en temas de solicitud de funcionalidad, precios, cumplimiento y errores, con las referencias y fragmentos de los tickets fuente.

kb

• zammad-cli kb browse - Imprimir la base de conocimiento como un árbol de categorías/respuestas analizado desde el paquete de inicio.
• zammad-cli kb search - Búsqueda de texto en títulos y cuerpos de respuestas de la KB desde el paquete de inicio en vivo.
• zammad-cli kb get - Resolver un ID de respuesta de la KB desde el paquete de inicio a su cuerpo traducido completo.

events

• zammad-cli events list - Listar los eventos de Zammad que webhooks listen registró después de un cursor, del más antiguo al más reciente (local, sin llamada a Zammad).

webhooks

• zammad-cli webhooks register - Crear los webhooks y activadores de Zammad que llaman a webhooks listen (escribe solo con --yes).
• zammad-cli webhooks listen - Recibir, verificar y registrar webhooks de Zammad hasta que se detenga (solo CLI).
• zammad-cli webhooks status - Mostrar los webhooks y activadores registrados y de dónde viene el secreto (nunca el secreto).
• zammad-cli webhooks unregister - Eliminar lo que webhooks register creó (escribe solo con --yes).

overdue

• zammad-cli overdue - Encontrar tickets que envejecen y aún están en nuevo/abierto/pendiente más allá de un umbral, ponderados por prioridad para que los peores suban a la cima.

ticket

• zammad-cli ticket note - Añadir una nota interna o visible para el socio a un ticket en una línea, con valores predeterminados correctos de tipo de contenido.

Encontrar el comando correcto

Cuando sabes lo que quieres hacer pero no qué comando lo hace, pregunta directamente al CLI:

zammad-cli which "<capacidad en tus propias palabras>"

which resuelve una consulta de capacidad en lenguaje natural al comando que mejor coincide del índice de características seleccionadas de este CLI. Código de salida 0 significa al menos una coincidencia; código de salida 2 significa que no hay suficiente confianza.