Diagnose Clickhouse Clusters

When your ClickHouse cluster is acting up, this skill cuts through the noise. It runs standardized health checks across replication lag, disk usage, part counts, and errors, then formats the findings into clean severity tables instead of making you parse raw SQL results. The real value is the RCA mode: ask "why is part count high" and it scores potential causes with actual evidence from your cluster, not generic advice. It enforces structured output so you get concrete remediation steps rather than theory. Works well for bounded time windows if you're debugging historical incidents. Currently supports high part count and general symptoms. If you maintain ClickHouse in production and want faster triage without writing custom diagnostic queries every time, this saves repetitive work.

GitHub stars: 320
last updated: May 14, 2026

View on GitHub

Install

$ npx -y skills add frankchen021/datastoria --skill diagnose-clickhouse-clusters --agent claude-code

Installs into .claude/skills of the current project.

Files

Tool Usage Rules

Call collect_cluster_status before health conclusions about current cluster health.
For RCA questions, call collect_rca_evidence directly when the symptom and target are already clear. Use collect_cluster_status first only when you need current health context, severity/outliers, or help choosing the RCA symptom/scope.
Use only supported Phase 1 RCA symptoms: high_part_count and unknown.
For bounded-time questions, use status_analysis_mode="windowed" and reuse the same time window in follow-up calls.
If user asks for a chart, use the visualization skill. Do not emit chart specs directly from this skill.
Do not invent custom health-check SQL. Use tool outputs as the source of truth.

Workflow (MANDATORY)

Determine whether the user asks for status only, or root cause ("why", "root cause", "reason", "caused by", "explain").
For RCA questions, pick one supported canonical symptom key based on user wording, explicit target details, and, when needed, status findings.
Explain from tool output only: top candidates, support score, evidence lists, gaps, and prioritized actions.