chdb-sql

Use when the user wants to run SQL — especially analytical SQL — on local files (parquet/csv/json), URLs, S3 paths, or remote databases (Postgres, MySQL, MongoDB, ClickHouse Cloud, Iceberg, Delta Lake) without setting up a server. Provides chDB — embedded ClickHouse SQL in Python with 1000+ functions, Session for stateful multi-step pipelines, parametrized queries, and cross-source joins via `s3()`, `mysql()`, `postgresql()`, `iceberg()`, `deltaLake()`, `remoteSecure()` table functions. TRIGGER when: user wants SQL on parquet/csv/files or across remote analytical sources; uses ClickHouse SQL features (window functions, windowFunnel, geoToH3, JSON path ops, Session, parametrized queries); imports `chdb` or calls `chdb.query()`. SKIP this skill for pandas-style DataFrame method-chaining (use chdb-datastore instead) or ClickHouse server administration.

Quality

95%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

High

Do not use without reviewing

Quality

Content

90%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A strong, token-efficient body: executable examples across every supported API, a clear API decision tree, and well-organized one-level-deep references. The main weaknesses are a broken reference to a nonexistent examples/examples.md file and the absence of explicit validation checkpoints in the multi-step Session/DB-API workflows.

Suggestions

Remove or create the 'examples/examples.md' reference — the examples/ directory does not exist in the bundle, so the link in the References section is broken.

Add a lightweight validation checkpoint to the Session and DB-API workflows (e.g., 'verify rows loaded: sess.query("SELECT count() FROM users").show()') so multi-step pipelines catch failures early.

Consolidate the inline reference links (line after the chdb.query() examples) with the References section to avoid duplicate navigation to the same three files.

Dimension	Reasoning	Score
Conciseness	The body is lean: a one-line pitch, an install command, a decision tree, and compact annotated code blocks, with no explanation of concepts Claude already knows (no 'what is SQL' or library-selection padding). Comments inside code ('# local files', '# parametrized') earn their tokens as navigation.	5 / 5
Actionability	All code is copy-paste executable and covers the common cases: one-off queries across files/DBs/S3/deltaLake, a cross-source join, Python(data) input, output formats ('DataFrame'), parametrized queries with params, Session pipelines, and DB-API 2.0 usage. The troubleshooting table pairs exact error strings ('DB::Exception: FILE_NOT_FOUND') with fixes.	5 / 5
Workflow Clarity	The 'Decision Tree: Pick the Right API' gives an unambiguous decision sequence, and the troubleshooting table plus scripts/verify_install.py provide error-recovery feedback. However, the multi-step flows (Session pipeline, DB-API connection) show no validation checkpoint between steps, which is a minor gap rather than a severe one since queries are non-destructive.	4 / 5
Progressive Disclosure	Good structure: an overview body with one-level-deep, clearly signaled references (table-functions.md, sql-functions.md, api-reference.md — all verified to exist). The gap is that 'examples/examples.md' is listed under References but the examples/ directory does not exist in the bundle, leaving a broken navigation link.	4 / 5
	Total	18 / 20 Passed

Description

100%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

An exemplary description: explicit what/when, comprehensive natural trigger terms including file extensions and import-level triggers, a concrete capability list, and an explicit SKIP clause for disambiguation. It is dense but every clause carries information, so no verbosity penalty applies.

Dimension	Reasoning	Score
Specificity	The description lists many concrete capabilities — 'run SQL ... on local files (parquet/csv/json), URLs, S3 paths, or remote databases', 'Session for stateful multi-step pipelines, parametrized queries, and cross-source joins via s3(), mysql(), postgresql(), iceberg(), deltaLake(), remoteSecure()' — with comprehensive coverage and no vague filler. It is dense but not padded; every clause states a distinct capability.	5 / 5
Completeness	It explicitly answers both questions: 'Use when the user wants to run SQL...' (when) and 'Provides chDB — embedded ClickHouse SQL in Python with 1000+ functions...' (what), reinforced by dedicated 'TRIGGER when:' and 'SKIP this skill for...' clauses. Both what and when are concrete and explicit.	5 / 5
Trigger Term Quality	Natural trigger phrases and synonyms are comprehensively covered: 'run SQL', 'analytical SQL', 'SQL on parquet/csv/files', file extensions (parquet/csv/json), named engines (Postgres, MySQL, MongoDB, ClickHouse Cloud, Iceberg, Delta Lake), and explicit code-level triggers ('imports chdb or calls chdb.query()'). This matches the top anchor, including extensions and synonyms.	5 / 5
Distinctiveness Conflict Risk	It carves a clear niche (embedded ClickHouse SQL in Python, no server) and actively disambiguates: 'SKIP this skill for pandas-style DataFrame method-chaining (use chdb-datastore instead) or ClickHouse server administration.' Conflict risk with neighboring skills is minimal.	5 / 5
	Total	20 / 20 Passed

Validation

93%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
relative_links	Relative link issues: 1 missing	Warning

	Total	15 / 16 Passed

Repository: chdb-io/chdb
Path: agent/skills/chdb-sql/SKILL.md
Commit: e93104d

Reviewed: 8 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.