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

87%

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

75%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.

The body is an efficient, code-heavy overview that routes users to the right API via a decision tree and points to real reference files for depth. It loses points mainly on two broken/mismatched path references (examples/examples.md does not exist; the verify_install.py path is wrong) and the verification step being relegated to troubleshooting rather than integrated into the workflow.

Suggestions

Fix or remove the dead reference to examples/examples.md (no such file exists in the bundle) — either add the examples file or drop the link from the References section.

Correct the verify_install.py path in the Troubleshooting table from 'agent/skills/chdb-sql/scripts/verify_install.py' to the actual bundle-relative path 'scripts/verify_install.py'.

Promote the verify_install.py environment check into a short 'Validate' step in the main workflow so installation is verified before running queries, adding an explicit feedback checkpoint.

Dimension	Reasoning	Score
Conciseness	Lean and code-forward with almost no padding and no explanation of concepts Claude already knows; a few short section intros and the restated opening line add minor framing that could be trimmed, keeping it just below a clean 5.	4 / 5
Actionability	Fully executable, copy-paste-ready code covers the common cases (query, Session, DB-API connect, parametrized, multiple table functions, output formats) plus a concrete troubleshooting table; the wrong verify_install.py path and a referenced-but-missing examples file are minor gaps that keep it off 5.	4 / 5
Workflow Clarity	The decision tree cleanly sequences API choice by use case and the skill is not destructive/batch so the destructive-cap does not apply; the bundled verify_install.py is mentioned only as a troubleshooting 'Environment check' rather than integrated as an explicit validation checkpoint, a minor gap below 5.	4 / 5
Progressive Disclosure	Good structure with a concise overview and clearly signaled one-level-deep references to real bundle files (api-reference.md, table-functions.md, sql-functions.md); the references to a non-existent examples/examples.md and a wrong verify script path slightly mar otherwise-good navigation, holding it below 5.	4 / 5
	Total	16 / 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.

The description is comprehensive, concrete, and well-bounded: it states the capability, gives explicit trigger conditions with natural keywords and file extensions, and clearly distinguishes the skill from adjacent ones via an explicit SKIP clause. Voice is consistently third person with no first/second-person drift.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete capabilities — running SQL on local files (parquet/csv/json), URLs, S3 paths, and remote databases, plus Session pipelines, parametrized queries, and cross-source joins via named table functions — giving comprehensive coverage with no real gaps.	5 / 5
Completeness	Explicitly answers both what ('Provides chDB — embedded ClickHouse SQL in Python…') and when, with a dedicated 'TRIGGER when:' clause of concrete triggers and an explicit 'SKIP this skill for…' boundary.	5 / 5
Trigger Term Quality	Comprehensive natural terms including file extensions (parquet/csv/json), user-facing phrases ('SQL on parquet/csv/files', 'imports chdb or calls chdb.query()'), and recognizable feature names like windowFunnel and geoToH3.	5 / 5
Distinctiveness Conflict Risk	Clear niche (embedded ClickHouse SQL) with an explicit SKIP clause redirecting pandas-style DataFrame work to chdb-datastore and ClickHouse server admin elsewhere, minimizing conflict risk.	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: db10b54

Reviewed: ~22 hours 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.