ClickHouse Best Practices: a skill that checks your ClickHouse schemas and queries against 31 rules

ClickHouse Inc's skill makes Claude check your ClickHouse tables, queries and insert plans against 31 written rules and name the rule behind each finding.

Installs: 22.1K; on skills.sh
Stars: 565; on GitHub
Files: 36; besides SKILL.md
Updated: Oct 2026; last repo commit

The skill tells Claude to look up its rule files before it answers any ClickHouse question, apply the ones that fit, and cite them as "Per rule-name". The 31 rules cover primary keys, data types, partitioning, JOINs, skipping indices, materialized views, insert batching, updates and deletes, and how an agent should connect to and explore a database.

It triggers on CREATE TABLE and ALTER TABLE statements, ORDER BY or PRIMARY KEY talk, slow queries, JOIN tuning, ingestion design and agent access to ClickHouse. A review comes back as a list of rules checked, violations (current, required, fix) and prioritised recommendations. The skill bundles no scripts. It is Markdown rules plus one compiled file, AGENTS.md, that holds all of them in one place.

The rules also describe how an agent connects to ClickHouse. If you let Claude run queries, read the permissions section below first.

Good for

Developers designing ClickHouse tables who want ORDER BY, types and partitions reviewed
Engineers fixing slow ClickHouse queries and JOINs
Teams that let an AI agent query ClickHouse and want guard rails on those queries

Install clickhouse-best-practices

Claude Code

Copy this prompt.

Install the clickhouse-best-practices skill in Claude Code. Run this command:

npx skills add https://github.com/clickhouse/agent-skills --skill clickhouse-best-practices

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires Node.js.

From its listing on skills.sh. Source.

What's in the skill

When it loads

MUST USE when reviewing ClickHouse schemas, queries, or configurations. Contains 31 rules that MUST be checked before providing recommendations. Always read relevant rule files and cite specific rules in responses.

Sections in SKILL.md

IMPORTANT: How to Apply This Skill
Agent Connectivity & Query Workflow
Subagent architecture notes
Review Procedures
For Schema Reviews (CREATE TABLE, ALTER TABLE)
For Query Reviews (SELECT, JOIN, aggregations)
For Insert Strategy Reviews (data ingestion, updates, deletes)
Output Format
Rules Checked
Findings
Violations
Compliant
Recommendations
Rule Categories by Priority
Quick Reference
Schema Design - Primary Key (CRITICAL)

Key facts

Author: ClickHouse Inc
License: Apache-2.0
Repository: clickhouse/agent-skills
Installs on skills.sh: 22,118 as of 2026-11-02
GitHub stars: 565 as of 2026-11-02
Last repo commit: 2026-10-30
Files in the skill folder: 37 files including SKILL.md
skills.sh audits: Gen Agent Trust Hub pass, Socket pass, Snyk pass
Version: 0.4.0
Described by the repo as: The official Agent Skills for ClickHouse

What it includes

Checks CREATE TABLE and ALTER TABLE against 9 schema rules
Reads the primary key, data type and partitioning rules in order. It checks column order in ORDER BY from low to high cardinality, numeric sizes, LowCardinality, Nullable vs DEFAULT and partition counts of 100 to 1,000.
Schema review
Checks SELECT, JOIN and aggregation queries against 5 rules
Looks at JOIN algorithm choice, filtering before the join, ANY JOIN, skipping indices and whether filters use the ORDER BY prefix.
Query review
Checks batching, updates and deletes against 5 rules
Looks for batches of 10K to 100K rows, alternatives to ALTER TABLE UPDATE, lightweight DELETE or DROP PARTITION, async inserts and OPTIMIZE TABLE risks.
Insert strategy review
Connect, discover the schema, plan, run with limits, recover
The agent rules ask Claude to connect over MCP or the ClickHouse CLI, explore databases, tables, columns and sort keys, then run queries with LIMIT and timeouts.
Network · Agent connectivity and query workflow
Rules checked, violations, compliant items, recommendations
Every review lists each rule as compliant or violated, then findings with current state, required state and fix.
Review report format
All 31 rules expanded in one file
A compiled copy of every rule so Claude can check several at once without opening each file.
AGENTS.md

From the official docs

Permissions

Medium risk

If you let Claude connect to a live ClickHouse database, a bad query can scan or load a lot of data. Use a read-only database user and keep write access off.

What it can do

Read your data
Create and change things
Delete things
Read-only modeHow to turn it on

Watch out for

Rules cover connecting Claude to your database
The skill bundles no scripts, but its agent-connect-mcp rule shows `pip install mcp-clickhouse`, MCP, ClickHouse CLI and curl commands that use a database password (the curl example sends it in a header). Use a database user with only the access you want Claude to have.
Self-hosted MCP can be set to allow writes
The rules show an environment variable that turns on write access for mcp-clickhouse. Leave it unset unless Claude needs to change data.
The rules tell agents to cap query cost
The agent-query-safety rule asks for LIMIT, scan caps and a max execution time on every agent-written query. Check that Claude includes them before you run a query on a large table.

Technical details

Turning on read-only	The agent-connect-mcp rule describes the hosted ClickHouse Cloud MCP server as read-only, and says writes on the self-hosted MCP server need CLICKHOUSE_ALLOW_WRITE_ACCESS=true.
Talks to	Rules show how to connect to a ClickHouse Cloud MCP server, the ClickHouse CLI or its HTTP interface, using your host and credentials

Questions

What does the ClickHouse Best Practices skill do?

It makes Claude check ClickHouse schemas, queries and insert plans against 31 written rules before it answers, and cite the rule it used. If no rule fits, SKILL.md tells Claude to fall back on its own ClickHouse knowledge or documentation.

How do I install it in Claude Code, the Claude app or Codex?

Use the install box above. The README documents npx skills add clickhouse/agent-skills, which finds the agents you have and asks where to install, and a clickhousectl skills command. The README lists Claude Code (.claude/skills/) and Codex (.codex/skills/) among supported agents. It does not describe a Claude app upload.

Does it need an API key or a ClickHouse connection?

Reviewing code you paste in needs neither. The agent rules cover connecting to a live database, with credentials such as a host, user and password or a sign-in to the hosted ClickHouse Cloud MCP server.

Is it safe to install?

It is Markdown rules and bundles no scripts. The risk comes from what you let Claude do with a database connection. The rules say to cap every agent query with a LIMIT and a time limit, and one rule shows how to switch on write access for a self-hosted MCP server, so keep that switch off unless you need it.

Does it work with ClickHouse Cloud and self-hosted ClickHouse?

Yes. The README says the skills work with open-source ClickHouse and managed ClickHouse Cloud.

What else is in the clickhouse/agent-skills repo?

The repo holds other ClickHouse skills, including one for chdb, the in-process ClickHouse for Python. This page covers only clickhouse-best-practices, which installs on its own.

Information

updated Nov 2, 2026

Repository: clickhouse/agent-skills
Folder: skills/clickhouse-best-practices

clickhouse/agent-skills skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 4

SKILL.md · github.com
agent-skills README · github.com
agent-connect-mcp rule · github.com
agent-query-safety rule · github.com