SQL Expert
ClickHouse SQL rules: leading-PK filters, qualified names, uniq over uniqExact
Test report
- Verdict
- Works with setup
- Score
- Tested
- Jul 21, 2026
- Environment
- Claude Code 2.x (agent harness)
- Upstream re-checked
- Aug 10, 2026 · 4b8b2a5
Cloned the repo (GitHub API was rate-limited, so I used git), found SKILL.md at resources/skills/sql-expert/, and installed it into a throwaway HOME=$(mktemp -d) — frontmatter parsed as valid YAML with name=sql-expert and a 129-char description. Spot-checked raw fetches: SKILL.md 200 and clickhouse-system-queries/references/system-query-log.md 200, but sql-expert/references/system-query-log.md is 404, so the body's relative reference dangles when the skill is installed alone; no curl|sh, base64, or injection text anywhere in resources/skills/. Trigger judgments, all 5 correct: YES on "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"; NO on "Write a Postgres query with a lateral join for each customer's latest order" and "Analyze this CSV of sales figures and tell me which region grew fastest" — though the description's second sentence ("use this when the user needs data, queries, or analysis") has no ClickHouse qualifier and is a real over-trigger hazard. Output test on one MergeTree table (PARTITION BY toYYYYMM(event_date), ORDER BY (event_date, site_id, event_time)): baseline.sql produced `FROM page_views WHERE site_id = 42 AND event_time >= now() - INTERVAL 7 DAY ... uniqExact(user_id) ... LIMIT 10;` while skill.sql produced `FROM analytics.page_views WHERE event_date >= toDate(now() - INTERVAL 7 DAY) AND event_time >= ... AND site_id = 42 ... uniq(user_id) ... LIMIT 10` with no semicolon — four diff hunks, the load-bearing one being the added event_date predicate that the baseline omits, which is what lets ClickHouse prune partitions and use the sparse index when filtering the secondary PK column site_id. I could not verify that with EXPLAIN (no clickhouse, clickhouse-local, or docker on this machine), and I could not execute the skill's own CRITICAL RULE — validate_sql — because that tool ships with the DataStoria web app, hence verdict "setup" rather than "pass".
Scored on four weighted criteria — install, triggering, output vs. baseline, docs. How scoring works
- Installs cleanly 4/5
- Triggers reliably 5/5
- Output vs. baseline 6/10
- Docs & honesty 3/5
What SQL Expert does
A ClickHouse SQL authoring ruleset that constrains how queries are written: fully qualified table names, no trailing semicolons, mandatory LIMIT on exploration queries, bounded time windows, a filter on the leading primary-key column whenever a secondary column is filtered, uniq() instead of uniqExact(), and smaller table on the right side of joins. Triggers when the user asks to write, fix, or optimize a ClickHouse query, or to pull data from a ClickHouse table. Its schema-discovery and mandatory validate_sql/execute_sql workflow depend on tools supplied by the DataStoria web app, so in plain Claude Code only the SQL-writing rules apply.
How to install SQL Expert
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
Skills live in ~/.claude/skills/ (global) or .claude/skills/
(per-project). Restart Claude Code after installing.
Commands — how to trigger SQL Expert
-
/sql-expertClickHouse SQL rules: leading-PK filters, qualified names, uniq over uniqExact
It also activates on plain-language prompts like these:
-
Write a ClickHouse query to aggregate daily sales -
Optimize this slow ClickHouse SQL query -
Validate this ClickHouse query for correctness
Frequently asked questions
- Is the SQL Expert skill free?
- Yes. The skill itself is free from FrankChen021/datastoria. SkillProof publishes the install command and an independent test verdict at no cost.
- Does SQL Expert work with Claude Code?
- We tested it with Claude Code 2.x (agent harness) on Jul 21, 2026. Verdict: Works with setup. Cloned the repo (GitHub API was rate-limited, so I used git), found SKILL.md at resources/skills/sql-expert/, and installed it into a throwaway HOME=$(mktemp -d) — frontmatter parsed as valid YAML with name=sql-expert and a 129-char description. Spot-checked raw fetches: SKILL.md 200 and clickhouse-system-queries/references/system-query-log.md 200, but sql-expert/references/system-query-log.md is 404, so the body's relative reference dangles when the skill is installed alone; no curl|sh, base64, or injection text anywhere in resources/skills/. Trigger judgments, all 5 correct: YES on "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"; NO on "Write a Postgres query with a lateral join for each customer's latest order" and "Analyze this CSV of sales figures and tell me which region grew fastest" — though the description's second sentence ("use this when the user needs data, queries, or analysis") has no ClickHouse qualifier and is a real over-trigger hazard. Output test on one MergeTree table (PARTITION BY toYYYYMM(event_date), ORDER BY (event_date, site_id, event_time)): baseline.sql produced `FROM page_views WHERE site_id = 42 AND event_time >= now() - INTERVAL 7 DAY ... uniqExact(user_id) ... LIMIT 10;` while skill.sql produced `FROM analytics.page_views WHERE event_date >= toDate(now() - INTERVAL 7 DAY) AND event_time >= ... AND site_id = 42 ... uniq(user_id) ... LIMIT 10` with no semicolon — four diff hunks, the load-bearing one being the added event_date predicate that the baseline omits, which is what lets ClickHouse prune partitions and use the sparse index when filtering the secondary PK column site_id. I could not verify that with EXPLAIN (no clickhouse, clickhouse-local, or docker on this machine), and I could not execute the skill's own CRITICAL RULE — validate_sql — because that tool ships with the DataStoria web app, hence verdict "setup" rather than "pass".
- What is the SQL Expert SkillProof Score?
- 7.2/10 — installs cleanly 4/5, triggers reliably 5/5, output vs. baseline 6/10, docs & honesty 3/5.
- How do I install SQL Expert?
- Copy the install command from this page, run it in your terminal, and restart Claude Code. Skills live in ~/.claude/skills/ (global) or .claude/skills/ inside a project.
- Can I use SQL Expert with Cursor, Copilot, Gemini CLI, Codex or other AI tools?
- The SKILL.md format is native to Claude (Claude Code, Desktop, claude.ai). The instructions inside adapt to other assistants: Cursor rules, GitHub Copilot instructions, Windsurf rules, Custom GPTs, AGENTS.md for OpenAI Codex, and GEMINI.md for Google Gemini CLI — our conversion guides cover each, and the free converter on the tools page does the wrapping for you.