Clickhouse Best Practices

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.

562 stars 38 forksDatabases

Install

skills CLI (Claude Code, Cursor, Codex and more)

npx skills add ClickHouse/agent-skills --skill clickhouse-best-practices

Manual install

git clone --depth 1 https://github.com/ClickHouse/agent-skills.git /tmp/agent-skills
mkdir -p ~/.claude/skills
cp -r /tmp/agent-skills/skills/clickhouse-best-practices ~/.claude/skills/clickhouse-best-practices

Personal skills live in ~/.claude/skills. Use .claude/skills in a project folder to share a skill with your team.

From the SKILL.md

# ClickHouse Best Practices

Comprehensive guidance for ClickHouse covering schema design, query optimization, data ingestion, and AI agent connectivity. Contains 31 rules across 4 main categories (schema, query, insert, agent), prioritized by impact.

> **Official docs:** [ClickHouse Best Practices](https://clickhouse.com/docs/best-practices)

## IMPORTANT: How to Apply This Skill

**Before answering ClickHouse questions, follow this priority order:**

1. **Check for applicable rules** in the `rules/` directory
2. **If rules exist:** Apply them and cite them in your response using "Per `rule-name`..."
3. **If no rule exists:** Use the LLM's ClickHouse knowledge or search documentation
4. **If uncertain:** Use web search for current best practices
5. **Always cite your source:** rule name, "general ClickHouse guidance", or URL

**Why rules take priority:** ClickHouse has specific behaviors (columnar storage, sparse indexes, merge tree mechanics) where general database intuition can be misleading. The rules encode validated, ClickHouse-specific guidance.

---

## Agent Connectivity & Query Workflow

Before querying ClickHouse, agents must establish a connection and follow the discovery workflow:

1. `rules/agent-connect-mcp.md` - Connection setup (MCP + CLI), credential discovery, output format selection
2. `rules/agent-discovery-schema.md` - **CRITICAL**: 7-step schema discovery workflow

Read the full skill on GitHub

Details

Skill name: clickhouse-best-practices
Repository: ClickHouse/agent-skills
Path: skills/clickhouse-best-practices/SKILL.md
License: Apache-2.0
Repo updated: 30 October 2026
Listed in: heilcheng/awesome-agent-skills

FAQ

What does the Clickhouse Best Practices skill do?

How do I install the Clickhouse Best Practices skill?

skills CLI (Claude Code, Cursor, Codex and more): npx skills add ClickHouse/agent-skills --skill clickhouse-best-practices. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.

Is Clickhouse Best Practices popular?

It lives in ClickHouse/agent-skills, which has 562 GitHub stars and 38 forks, and is included in 1 curated skill list.

Related skills

Attach Db

613

duckdb/duckdb-skills

Attach a DuckDB database file for use with /duckdb-skills:query. Explores the schema (tables, columns, row counts) and writes a SQL state file so subsequent queries can restore this session automatically via duckdb -init.

DatabasesIn 1 list37

PostgreSQL Queries

448

sanjay3290/ai-skills

Execute safe read-only SQL queries against PostgreSQL databases. Analyze and explore your database with Claude.

DatabasesIn 4 lists49

Query

613

duckdb/duckdb-skills

Run SQL queries against the attached DuckDB database or ad-hoc against files. Accepts raw SQL or natural language questions. Uses DuckDB Friendly SQL idioms.

DatabasesIn 1 list37

Mysql

448

sanjay3290/ai-skills

Execute read-only SQL queries against multiple MySQL databases. Use when: (1) querying MySQL databases, (2) exploring database schemas/tables, (3) running SELECT queries for data analysis, (4) checking database contents. Supports multiple database connections with descriptions for intelligent auto-selection. Blocks all write operations (INSERT, UPDATE, DELETE, DROP, etc.) for safety.

DatabasesIn 4 lists49

Better Auth Best Practices

227

better-auth/skills

Configure Better Auth server and client, set up database adapters, manage sessions, add plugins, and handle environment variables. Use when users mention Better Auth, betterauth, auth.ts, or need to set up TypeScript authentication with email/password, OAuth, or plugin configuration.

DatabasesIn 1 list37

Mssql

448

sanjay3290/ai-skills

Execute read-only SQL queries against multiple Microsoft SQL Server databases. Use when: (1) querying MSSQL/SQL Server databases, (2) exploring database schemas/tables, (3) running SELECT queries for data analysis, (4) checking database contents. Supports multiple database connections with descriptions for intelligent auto-selection. Blocks all write operations (INSERT, UPDATE, DELETE, DROP, etc.) for safety.

DatabasesIn 4 lists49

Browse the most popular Claude skills, all databases skills, or write your own with the skills generator.