Zammad - Claude Code 스킬
사전 요구 사항: CLI 설치
이 스킬은 zammad-cli 바이너리를 사용합니다. 이 스킬의 명령어를 실행하기 전에 CLI가 설치되어 있는지 반드시 확인해야 합니다. 설치되어 있지 않다면 먼저 설치하세요:
- macOS / Linux:
bash <(curl -fsSL https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/zammad/install.sh) - Windows (PowerShell):
iwr -useb https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/zammad/install.ps1 | iex - 확인:
zammad-cli --version ~/.local/bin(macOS / Linux) 또는%LOCALAPPDATA%\Programs\msp-skills(Windows)가$PATH에 포함되어 있는지 확인하세요.
인스톨러는 zammad-cli 및 zammad-mcp 바이너리를 ~/.local/bin(macOS / Linux) 또는 %LOCALAPPDATA%\Programs\msp-skills(Windows)에 다운로드합니다. 이 인스톨러는 에이전트에 스킬을 등록하지 않으며 MCP 클라이언트 설정을 작성하지 않습니다. 해당 설정은 mcp-install.md를 참조하세요.
설치 후 --version이 "command not found"를 보고하면 런타임이 $PATH에서 바이너리 디렉토리를 찾을 수 없다는 의미입니다. 확인이 완료될 때까지 스킬 명령어를 진행하지 마세요.
Zammad REST + Knowledge Base 전체 표면을 다루는 단일 Go 바이너리로, 오프라인 SQLite 저장소, 구조화된 --json/--select 출력, 모든 쓰기 작업에 --dry-run을 지원합니다. 기본 작업 외에도 동기화된 티켓을 기반으로 계산된 팀 관리 계층(agent-load, agent-trend), 고객 상태, 이탈 위험, 지연 백로그, 에스컬레이션 심사, 피드백 마이닝을 추가합니다. 모든 Zammad 인스턴스에서 작동하며 인스턴스 URL과 토큰만 설정하면 됩니다.
CLI 사용 시기
에이전트가 Zammad 티켓 및 기술 자료 콘텐츠를 읽거나, 검색하거나, 분류해야 하거나, 팀 관리 관련 질문(누가 과부하 상태인지, 어떤 고객이 위험에 처했는지, 무엇이 장기간 방치되었는지, 이탈 가능성이 있는 고객은 누구인지, 반복되는 피드백 주제는 무엇인지)에 답해야 할 때 이 CLI를 사용하세요. 지원 운영 자동화, 스탠드업 미팅, 계정 상태 검토 등 여러 티켓을 집계해야 하는 경우에 적합합니다.
사용 금지 조건
다음과 같은 경우에는 이 CLI를 사용하지 마세요:
- 고객 대상 마케팅 이메일 전송 - 이 도구는 티켓 게시글을 관리하는 도구이지 캠페인을 위한 도구가 아닙니다.
- Zammad 트리거, 자동화, SLA 또는 채널 설정 - 이러한 기능은 관리 콘솔 기능으로 여기서 제공되지 않습니다.
escalate/churn/feedback을 공식적인 감정 분석으로 신뢰하지 마세요. 이는 휴리스틱 키워드 분류 도구로, 사람이나 에이전트가 판단할 신호를 제공할 뿐입니다.
고유 기능
팀 관리
-
agent-load- 각 에이전트의 현재 티켓 부하를 상태별(열림/대기중/백로그)로 표시하여 업무가 쌓이기 전에 균형을 맞출 수 있습니다.누가 과부하 상태인지 또는 지원팀의 업무 분배가 현재 어떻게 되어 있는지 물어볼 때 사용하세요.
zammad-cli agent-load --json -
agent-trend- 각 에이전트의 대기열이 지난 N주 동안 증가 또는 감소 추세인지, 열림 대 마감 델타와 함께 표시합니다.팀이 시간이 지남에 따라 작업을 따라잡고 있는지 또는 뒤쳐지고 있는지 물어볼 때 사용하세요.
zammad-cli agent-trend --weeks 2 --json -
customer-health- 열린 티켓 수, 가장 오래된 열린 티켓의 경과 시간, 재오픈율, 속도 및 마지막 활동을 기반으로 조직의 상태 신호를 순위화합니다.고객이 불평하기 전에 어려움을 겪고 있는 고객을 찾아낼 때 사용하세요.
zammad-cli customer-health --at-risk --json -
overdue- 임계값을 초과하여 아직 new/open/pending 상태인 노화 티켓을 찾아내며, 우선순위에 따라 가중치를 부여하여 최악의 티켓이 상위에 오르도록 합니다.SLA 위반 직전이거나 오래 방치된 티켓을 잡아낼 때 사용하세요.
zammad-cli overdue --days 3 --json -
escalate- 최근 고객 메시지가 화난 것으로 읽히는 활성 티켓(휴리스틱 부정 신호 스캔)을 표시하며, 적중 횟수, 경과 시간 및 우선순위로 순위를 매기고 일치하는 스니펫을 보여줍니다.화난 것으로 보이는 고객을 찾아 에스컬레이션해야 할 때 사용하세요. 스니펫이 포함된 키워드 분류이므로 최종 판단은 직접 내려야 합니다.
zammad-cli escalate --json -
churn-risk- 각 조직의 이탈 위험을 열린 백로그, 연체 티켓, 응답 없는 대기 중 티켓, 부정적 감정의 고객 메시지 등을 기반으로 점수화하고 기여 요인을 나열합니다.이탈을 사전에 방지할 때 사용하세요. 기여 요인을 제시하므로 직접 판단하고 조치를 취할 수 있습니다.
zammad-cli churn-risk --json -
feedback-scan- 티켓 및 게시글 텍스트를 기능 요청, 가격, 규정 준수, 버그 테마로 분류하고 소스 티켓 참조 및 스니펫을 함께 제공합니다.고객이 기능, 가격, 규정 준수 등에 대해 지속적으로 요청하는 내용을 마이닝할 때 사용하세요.
zammad-cli feedback-scan --bucket pricing --json
기술 자료
-
kb browse- 초기화 번들에서 파싱된 지식 베이스를 카테고리/답변 트리로 출력합니다.답변을 읽거나 검색하기 전에 KB 구조를 확인할 때 사용하세요.
zammad-cli kb browse -
kb search- 라이브 KB 초기화 번들에서 KB 답변 제목 및 본문을 텍스트 검색합니다.키워드로 올바른 KB 답변을 찾을 때 사용하세요.
zammad-cli kb search "restore" --json -
kb get- 초기화 번들에서 KB 답변 ID를 해결하여 전체 번역된 본문을 가져옵니다.KB 답변의 전체 내용을 읽을 때 사용하세요.
zammad-cli kb get 42
티켓 편의 기능
-
ticket note- 한 줄로 티켓에 내부 또는 파트너 공개 노트를 추가하고 올바른 콘텐츠 유형 기본값을 적용합니다.게시글 페이로드를 직접 구성하지 않고 티켓에 작업 내용을 기록할 때 사용하세요.
zammad-cli ticket note 12345 --body "조사 중, 로그 대기 중" --internal --dry-run
웹훅 (폴링 불필요)
Zammad가 티켓 생성/업데이트 또는 게시글 추가 시 이 머신을 호출할 수 있으므로 폴링이 필요 없습니다.
# 한 번만 실행 (admin.webhook 및 admin.trigger 권한이 있는 토큰 필요)
zammad-cli webhooks register --endpoint http://127.0.0.1:8789/zammad --yes
# Zammad가 게시하는 머신에서 계속 실행
zammad-cli webhooks listen
# 도착한 이벤트 읽기; 다음 번에 --since로 반환된 커서 전달
zammad-cli events list --since 0 --json
register는 이벤트(zammad.ticket.created,zammad.ticket.updated,zammad.article.created)당 하나의 Zammad 웹훅과 하나의 트리거를 생성합니다. 서명 시크릿을 생성하여 API 토큰 옆에 저장하며, 소유자만 읽을 수 있습니다.ZAMMAD_WEBHOOK_SECRET으로 재정의할 수 있습니다. 시크릿은 절대 출력되지 않습니다.webhooks status는 시크릿의 출처만 표시합니다.listen은 기본적으로 이 머신(127.0.0.1, 포트 8789)에만 바인딩되며 시크릿 없이는 시작을 거부합니다. 모든 요청은 Zammad의X-Hub-Signature를 포함해야 하며, 본문을 읽기 전에 검증됩니다. 이미 처리된 전달은 무시되고 1MiB를 초과하는 본문은 거부됩니다.- 웹훅은 ID만 전달합니다. 리스너는 API를 통해 티켓을 가져오고 이벤트를 기록하므로 고객 텍스트가 웹훅을 통해 전송되지 않습니다.
- Zammad는 약 2분 동안 5회 시도 후 전달을 포기합니다.
listen이 시작될 때마다 중단된 동안 변경된 사항을 먼저 기록합니다.listen이 실행 중이지만 연결할 수 없는 경우(네트워크 중단) Zammad가 포기한 전달은 기록되지 않습니다. - Zammad가 리스너에 도달할 수 있어야 합니다. 동일 서버의 자체 호스팅 Zammad는 기본 설정으로 작동합니다. LAN의 다른 머신에 있는 Zammad는
listen --addr <lan-ip>:8789 --tls-cert <file> --tls-key <file>및https://엔드포인트가 필요합니다. Zammad Cloud 인스턴스는 LAN의 머신에 도달할 수 없습니다. - 사용자가 새 티켓이나 변경된 티켓에 반응하려 할 때 사용하세요.
events list --since <cursor>로 읽고 반환된 커서를 유지하세요. 티켓 텍스트는tickets get <id>로 가져옵니다. - MCP를 통해
events_list는 기록된 이벤트를 읽습니다(읽기 전용, Zammad 호출 없음).webhooks_register와webhooks_unregister는confirm: true가 있을 때만 Zammad를 변경합니다.listen은 CLI 전용입니다.
명령어 참조
articles - 티켓 게시글(노트 및 이메일) 읽기 및 추가
zammad-cli articles by-ticket- 티켓의 모든 게시글 나열zammad-cli articles create- 티켓에 게시글(노트 또는 이메일) 추가zammad-cli articles get- ID로 단일 게시글 가져오기
groups - 티켓 라우팅 그룹
zammad-cli groups get- ID로 그룹 가져오기zammad-cli groups list- 모든 그룹 나열
kb - 기술 자료 카테고리 및 답변
zammad-cli kb answer-create- KB 답변 생성. translations_attributes를 JSON으로 전달한 후 publish 또는 internal로 표시.zammad-cli kb answer-delete- KB 답변 삭제 (KB 편집자 권한 필요)zammad-cli kb answer-internal- KB 답변을 내부용으로 표시 (에이전트 전용)zammad-cli kb answer-publish- KB 답변 공개 (공개 설정)zammad-cli kb category-create- KB 카테고리 생성. translations_attributes를 JSON으로 전달.zammad-cli kb init- 전체 기술 자료 번들(카테고리, 답변, 번역) 가져오기. 'kb browse/search/get'에서 사용.
organizations - 조직(고객/파트너) 읽기 및 관리
zammad-cli organizations create- 조직 생성zammad-cli organizations get- ID로 조직 가져오기zammad-cli organizations list- 조직 나열 (페이지네이션)zammad-cli organizations search- 이름 또는 사용자 정의 필드로 조직 검색zammad-cli organizations update- 조직 업데이트
overviews - 에이전트 티켓 개요 (저장된 보기)
zammad-cli overviews get- ID로 개요(및 해당 티켓) 가져오기zammad-cli overviews list- 모든 개요 나열
priorities - 티켓 우선순위 참조 (id -> 이름 매핑)
zammad-cli priorities- 티켓 우선순위 나열
states - 티켓 상태 참조 (id -> 이름 매핑)
zammad-cli states- 티켓 상태 나열
tags - 티켓 태그
zammad-cli tags add- 객체에 태그 추가zammad-cli tags all- 인스턴스에 정의된 모든 태그 나열 (용어집)zammad-cli tags list- 객체의 태그 나열 (기본값: 티켓)zammad-cli tags remove- 객체에서 태그 제거
tickets - Zammad 티켓 읽기, 검색, 생성 및 변경
zammad-cli tickets create- 티켓 생성. 제목, 그룹, 고객 및 초기 게시글 제공.zammad-cli tickets delete- 티켓 영구 삭제 (관리자/삭제 권한 필요)zammad-cli tickets get- ID로 티켓 가져오기zammad-cli tickets list- 티켓 나열 (페이지네이션)zammad-cli tickets search- Zammad 쿼리 구문으로 티켓 검색 (예: 'state:open owner_id:3')zammad-cli tickets update- 티켓 업데이트 (상태, 우선순위, 소유자, 제목, 조직)
users - 사용자(에이전트 및 고객) 읽기 및 관리
zammad-cli users create- 사용자 생성zammad-cli users get- ID로 사용자 가져오기zammad-cli users list- 사용자 나열 (페이지네이션)zammad-cli users me- 인증된 사용자 가져오기 (인증 자체 확인)zammad-cli users search- 이메일, 이름 또는 쿼리로 사용자 검색 (예: organization_id:5)zammad-cli users update- 사용자 업데이트
agent-load
zammad-cli agent-load- 각 에이전트의 현재 티켓 부하를 상태별(열림/대기중/백로그)로 표시하여 업무가 쌓이기 전에 균형을 맞출 수 있습니다.
agent-trend
zammad-cli agent-trend- 각 에이전트의 대기열이 지난 N주 동안 증가 또는 감소 추세인지, 열림 대 마감 델타와 함께 표시합니다.
churn-risk
zammad-cli churn-risk- 각 조직의 이탈 위험을 열린 백로그, 연체 티켓, 응답 없는 대기 중 티켓, 부정적 감정의 고객 메시지 등을 기반으로 점수화하고 기여 요인을 나열합니다.
customer-health
zammad-cli customer-health- 열린 티켓 수, 가장 오래된 열린 티켓의 경과 시간, 재오픈율, 속도 및 마지막 활동을 기반으로 조직의 상태 신호를 순위화합니다.
escalate
zammad-cli escalate- 최근 고객 메시지가 화난 것으로 읽히는 활성 티켓(휴리스틱 부정 신호 스캔)을 표시하며, 적중 횟수, 경과 시간 및 우선순위로 순위를 매기고 일치하는 스니펫을 보여줍니다.
feedback-scan
zammad-cli feedback-scan- 티켓 및 게시글 텍스트를 기능 요청, 가격, 규정 준수, 버그 테마로 분류하고 소스 티켓 참조 및 스니펫을 함께 제공합니다.
kb
zammad-cli kb browse- 초기화 번들에서 파싱된 지식 베이스를 카테고리/답변 트리로 출력합니다.zammad-cli kb search- 라이브 KB 초기화 번들에서 KB 답변 제목 및 본문을 텍스트 검색합니다.zammad-cli kb get- 초기화 번들에서 KB 답변 ID를 해결하여 전체 번역된 본문을 가져옵니다.
events
zammad-cli events list-webhooks listen이 커서 이후에 기록한 Zammad 이벤트를 오래된 순서대로 나열합니다 (로컬, Zammad 호출 없음).
webhooks
zammad-cli webhooks register-webhooks listen을 호출하는 Zammad 웹훅 및 트리거를 생성합니다 (--yes가 있을 때만 쓰기).zammad-cli webhooks listen- 중지될 때까지 Zammad 웹훅을 수신, 확인 및 기록합니다 (CLI 전용).zammad-cli webhooks status- 등록된 웹훅 및 트리거와 시크릿의 출처를 표시합니다 (시크릿 자체는 표시하지 않음).zammad-cli webhooks unregister-webhooks register가 생성한 항목을 제거합니다 (--yes가 있을 때만 쓰기).
overdue
zammad-cli overdue- 임계값을 초과하여 아직 new/open/pending 상태인 노화 티켓을 찾아내며, 우선순위에 따라 가중치를 부여하여 최악의 티켓이 상위에 오르도록 합니다.
ticket
zammad-cli ticket note- 한 줄로 티켓에 내부 또는 파트너 공개 노트를 추가하고 올바른 콘텐츠 유형 기본값을 적용합니다.
올바른 명령어 찾기
수행하려는 작업은 알지만 어떤 명령어가 해당 작업을 수행하는지 모를 경우 CLI에 직접 물어보세요:
zammad-cli which "<원하는 기능을 자신의 언어로 설명>"
which는 자연어 기능 쿼리를 이 CLI의 큐레이팅된 기능 인덱스에서 가장 적합한 명령어로 매핑합니다. 종료 코드 0은 최소한 하나의 일치 항목이 있음을 의미하고, 종료 코드 2는 일치 항목이 없음을 의미합니다.
MCP 스킬 구성에 대한 자세한 내용은 mcp-install.md를 참조하세요.