SQL Expert
ClickHouse SQL-Regeln: führende PK-Filter, qualifizierte Namen, uniq über uniqExact
Funktioniert mit Setup
Was es kann
Ein ClickHouse SQL-Erstellungsregelwerk, das die Art und Weise, wie Abfragen geschrieben werden, einschränkt: vollständig qualifizierte Tabellennamen, keine nachgestellten Semikolons, obligatorisches LIMIT bei Explorationsabfragen, begrenzte Zeitfenster, ein Filter auf der führenden Primärschlüsselspalte, wenn eine sekundäre Spalte gefiltert wird, uniq() anstelle von uniqExact() und kleinere Tabelle auf der rechten Seite von Joins. Wird ausgelöst, wenn der Benutzer eine ClickHouse-Abfrage schreiben, korrigieren oder optimieren oder Daten aus einer ClickHouse-Tabelle abrufen möchte. Sein Schema-Discovery- und obligatorischer validate_sql/execute_sql-Workflow hängen von Tools ab, die von der DataStoria-Web-App bereitgestellt werden, daher gelten in reinem Claude Code nur die SQL-Schreibregeln.
Testbericht
Das Repo geklont (GitHub API war ratenbegrenzt, daher verwendete ich git), SKILL.md unter resources/skills/sql-expert/ gefunden und in ein temporäres HOME=$(mktemp -d) installiert — Frontmatter als gültiges YAML mit name=sql-expert und einer 129-Zeichen-Beschreibung geparst. Roh-Abrufe stichprobenartig überprüft: SKILL.md 200 und clickhouse-system-queries/references/system-query-log.md 200, aber sql-expert/references/system-query-log.md ist 404, sodass die relative Referenz des Bodys hängen bleibt, wenn der Skill allein installiert wird; kein curl|sh, base64 oder Injection-Text irgendwo in resources/skills/. Trigger-Urteile, alle 5 korrekt: JA bei „Write me a ClickHouse query for the top 10 slowest endpoints last week“, „I need a query against our ClickHouse events table showing daily unique users“, „Optimize this ClickHouse SQL, it's scanning the whole table“; NEIN bei „Write a Postgres query with a lateral join for each customer's latest order“ und „Analyze this CSV of sales figures and tell me which region grew fastest“ — obwohl der zweite Satz der Beschreibung („use this when the user needs data, queries, or analysis“) keinen ClickHouse-Qualifier hat und ein echtes Über-Trigger-Risiko darstellt. Output-Test an einer MergeTree-Tabelle (PARTITION BY toYYYYMM(event_date), ORDER BY (event_date, site_id, event_time)): baseline.sql produzierte `FROM page_views WHERE site_id = 42 AND event_time >= now() - INTERVAL 7 DAY ... uniqExact(user_id) ... LIMIT 10;` während skill.sql `FROM analytics.page_views WHERE event_date >= toDate(now() - INTERVAL 7 DAY) AND event_time >= ... AND site_id = 42 ... uniq(user_id) ... LIMIT 10` ohne Semikolon produzierte — vier Diff-Hunks, wobei der tragende das hinzugefügte event_date-Prädikat ist, das die Baseline weglässt, was ClickHouse ermöglicht, Partitionen zu kürzen und den Sparse-Index beim Filtern der sekundären PK-Spalte site_id zu verwenden. Ich konnte dies nicht mit EXPLAIN überprüfen (kein clickhouse, clickhouse-local oder Docker auf diesem Rechner), und ich konnte die EIGENE KRITISCHE REGEL des Skills — validate_sql — nicht ausführen, da dieses Tool mit der DataStoria-Web-App geliefert wird, daher das Urteil „setup“ statt „pass“.
Getestet am: 2026-07-21 · Claude Code 2.x (agent harness)
Installation
git clone --depth 1 https://github.com/FrankChen021/datastoria.git /tmp/sql-expert-src mkdir -p ~/.claude/skills cp -R /tmp/sql-expert-src/resources/skills/sql-expert ~/.claude/skills/sql-expert # The SKILL.md body calls tools provided by the DataStoria app, not by Claude Code: # validate_sql, execute_sql, get_tables, explore_schema, skill_resource, search_query_log # Without a ClickHouse MCP server exposing equivalents, Claude cannot run the skill's # "MANDATORY validation" step - only the syntax/optimization rules in sections 2 and 3 apply. # The body's `references/system-query-log.md` lives in a sibling skill, not this dir. To get it: # cp -R /tmp/sql-expert-src/resources/skills/clickhouse-system-queries ~/.claude/skills/clickhouse-system-queries # Sibling skills also referenced by the body: visualization, optimize-clickhouse-sql, # diagnose-clickhouse-errors, diagnose-clickhouse-clusters, source-code-inspection # Full experience (with the tools wired up): use the app at https://datastoria.app
Befehle & Beispiel-Prompts
/sql-expertClickHouse SQL-Regeln: führende PK-Filter, qualifizierte Namen, uniq über uniqExact
Skills reagieren auf normale Anfragen — keine Slash-Befehle nötig. Nach der Installation aktivieren Prompts wie diese den Skill (auf Englisch):
Write a ClickHouse query to aggregate daily salesOptimize this slow ClickHouse SQL queryValidate this ClickHouse query for correctness