Diagnose Clickhouse Errors
Mapea un código de error de ClickHouse a un playbook de diagnóstico por código y una respuesta de 3 secciones Causa/Solución
Funciona con configuración
Qué hace
Convierte un error de tiempo de ejecución de ClickHouse en una respuesta fija de Causa / Solución / Ejemplo extrayendo el código de error numérico y cargando un playbook por código (42, 47, 60, 115, 342 están incluidos). Se activa cuando un usuario pega una DB::Exception o nombra un código de error de ClickHouse y desea orientación sobre la causa y solución a nivel de base de datos, y explícitamente se remite a la inspección del código fuente cuando el objetivo es encontrar dónde se construyó el SQL fallido. La mayoría de los playbooks esperan un ClickHouse en vivo para ejecutar una búsqueda en system.columns / system.tables / system.settings, con un fallback documentado solo de texto cuando esa consulta no puede ejecutarse.
Informe de la prueba
La API de GitHub tenía límite de tasa, así que cloné el repositorio y encontré SKILL.md en resources/skills/diagnose-clickhouse-errors/; recuperé directamente SKILL.md, references/60.md y references/342.md (todos HTTP 200; un references/999.md inventado devolvió 404, confirmando que solo se envían 5 códigos), grep no encontró curl|sh, base64, credenciales o texto de inyección, y ejecuté el bloque de instalación en un HOME temporal=$(mktemp -d) donde colocó SKILL.md más los 5 archivos de referencia correctamente. Frases de activación que juzgué: DEBERÍA activarse — "My query failed with Code: 60. DB::Exception: Table analytics.evnts doesn't exist. (UNKNOWN_TABLE), what's wrong?", "ClickHouse throws error code 115 on my SETTINGS clause, how do I fix it?", "Getting NUMBER_OF_ARGUMENTS_DOESNT_MATCH from toStartOfInterval in ClickHouse"; NO DEBERÍA — "This ClickHouse query takes 40 seconds, help me speed it up" (optimización, no un fallo) y "Our Java service logs a ClickHouse UNKNOWN_TABLE error, find where in our repo the table name is built" (la descripción y una sección When-Not-To-Use explícitamente lo remiten a la inspección del código fuente); 5/5 correcto. La prueba de salida usó el error 342 porque references/342.md es el único playbook que no requiere la herramienta execute_sql faltante: la línea base nombró la columna `payload` faltante, dio verificaciones de solo lectura (system.replicas, clusterAllReplicas sobre system.columns) y tres opciones de remediación incluyendo `SYSTEM DROP REPLICA ... FROM TABLE events.page_views_local`, mientras que la ejecución seguida por la habilidad se redujo a ~180 palabras con encabezados ## Cause / ## Fix, la extracción obligatoria de fragmentos almacenados/analizados/locales, cero comandos mutantes y "escalate to the cluster maintainer / SRE" — más seguro para un incidente de producción pero estrictamente menos accionable para un Claude Code user que es el mantenedor, por lo que no lo califiqué mejor que la línea base. Veredicto: configuración: para 4 de los 5 códigos, el paso de evidencia es un `execute_sql` en vivo que no pude ejecutar, y tres nombres de herramientas en el cuerpo (skill_resource, execute_sql, ask_user_question) son internos del producto DataStoria que ningún README o nota de habilidad marca como no disponibles fuera de esa aplicación.
Probado el: 2026-07-21 · Claude Code 2.x (agent harness)
Instalación
git clone --depth 1 https://github.com/FrankChen021/datastoria.git /tmp/diagnose-clickhouse-errors-src
mkdir -p ~/.claude/skills
cp -R /tmp/diagnose-clickhouse-errors-src/resources/skills/diagnose-clickhouse-errors ~/.claude/skills/diagnose-clickhouse-errors
# Verified: places SKILL.md + references/{42,47,60,115,342}.md under ~/.claude/skills/diagnose-clickhouse-errors/
# The repo is the DataStoria web console (~large clone); only this one directory is needed.
# Sibling skills in the same folder that this one references: source-code-inspection, optimize-clickhouse-sql,
# clickhouse-system-queries, diagnose-clickhouse-clusters, sql-expert, visualization.
# MANUAL STEP: the skill body calls DataStoria-internal tools that do not exist in Claude Code:
# skill_resource -> read references/<code>.md yourself
# ask_user_question -> AskUserQuestion
# execute_sql -> needs a ClickHouse MCP server or a clickhouse-client you run by hand;
# without it, codes 42/47/60/115 fall back to text-only diagnosis (documented in each file). Comandos y prompts de ejemplo
/diagnose-clickhouse-errorsMapea un código de error de ClickHouse a un playbook de diagnóstico por código y una respuesta de 3 secciones Causa/Solución
Los skills se activan con peticiones en lenguaje natural, sin comandos que memorizar. Tras instalarlo, prompts como estos lo activan (en inglés):
Diagnose this ClickHouse error code 241Why did my ClickHouse query fail at runtimeExplain this ClickHouse memory limit exceeded error