Setting the issue. One moment.
Contents
Issue No. 37ClickHouse · Official
ClickHouse /agent-skills
The official Agent Skills for ClickHouse and ClickHouse Cloud
11 chapters · 36 minutes · 7,905 words
Install and provenance
npx skills add ClickHouse/agent-skills/plugin marketplace add ClickHouse/agent-skills- Owner
- ClickHouse · Organization
- Licence
- Apache-2.0
- Last updated
- Published from
- github.com/
ClickHouse/ agent-skills
Typeset in this issue’s own colours, resolved from the awesome-design-md registry.
Front matter
From the READMEClickHouse Agent Skills
The official Agent Skills for ClickHouse (opens in a new tab). These skills help LLMs and agents to adopt best practices when working with ClickHouse and chdb (opens in a new tab) (in-process ClickHouse for Python).
You can use these skills with open-source ClickHouse and managed ClickHouse Cloud. Try ClickHouse Cloud with $300 in free credits (opens in a new tab).
Installation
npx
npx skills add clickhouse/agent-skillsThe CLI auto-detects installed agents and prompts you to select where to install.
clickhousectl
Use the ClickHouse CLI clickhousectl (opens in a new tab) to install the agent skills:
clickhousectl skillsWhat is this?
Agent Skills are packaged instructions that extend AI coding agents (Claude Code, Cursor, Copilot, etc.) with domain-specific expertise. This repository provides skills for ClickHouse databases and chdb — covering schema design, query optimization, data ingestion patterns, and in-process analytics with Python.
When an agent loads these skills, it gains knowledge of ClickHouse best practices and chdb APIs, and can apply them while helping you design tables, write queries, analyze data, or troubleshoot performance issues.
Skills follow the open specification at agentskills.io (opens in a new tab).
Available Skills
ClickHouse Best Practices
28 rules covering schema design, query optimization, and data ingestion—prioritized by impact.
| Category | Rules | Impact |
|---|---|---|
| Primary Key Selection | 4 | CRITICAL |
| Data Type Selection | 5 | CRITICAL |
| JOIN Optimization | 5 | CRITICAL |
| Insert Batching | 1 | CRITICAL |
| Mutation Avoidance | 2 | CRITICAL |
| Partitioning Strategy | 4 | HIGH |
| Skipping Indices | 1 | HIGH |
| Materialized Views | 2 | HIGH |
| Async Inserts | 2 | HIGH |
| OPTIMIZE Avoidance | 1 | HIGH |
| JSON Usage | 1 | MEDIUM |
Location: skills/clickhouse-best-practices/ (opens in a new tab)
For humans: Read SKILL.md for an overview, or AGENTS.md (opens in a new tab) for the complete compiled guide.
For agents: The skill activates automatically when you work with ClickHouse—creating tables, writing queries, or designing data pipelines.
ClickHouse Architecture Advisor
5 decision frameworks covering workload-aware architecture decisions for real-time ClickHouse deployments.
| Decision Area | Impact |
|---|---|
| Ingestion Strategy | CRITICAL |
| Join & Enrichment Patterns | CRITICAL |
| Late-Arriving Data & Upserts | CRITICAL |
| Time-Series Partitioning | HIGH |
| Real-Time Pre-Aggregation | HIGH |
Complements clickhouse-best-practices by answering when, why, and how — not just what. All recommendations are explicitly classified as official, derived, or field guidance.
Location: skills/clickhouse-architecture-advisor/ (opens in a new tab)
For humans: Read SKILL.md for an overview, or AGENTS.md (opens in a new tab) for the compiled guide.
For agents: The skill activates during architecture design sessions — when choosing ingestion patterns, designing time-series schemas, selecting enrichment strategies, or handling mutable state.
ClickHouse JS Node Troubleshooting
Troubleshooting guide for the ClickHouse Node.js client (@clickhouse/client). Covers common failure modes including socket hang-up / ECONNRESET, Keep-Alive misconfiguration, data type mismatches, read-only user restrictions, proxy / pathname URL confusion, TLS certificate errors, compression issues, logging setup, and query parameter interpolation.
Location: skills/clickhouse-js-node-troubleshooting/ (opens in a new tab)
For agents: The skill activates when users report errors, unexpected behavior, or configuration questions involving the ClickHouse Node.js client — including vague symptoms like “my inserts keep failing” or “connection drops randomly” in a Node.js context. Not used for browser/Web client issues.
chdb DataStore
Pandas-compatible API for chdb — drop-in pandas replacement backed by ClickHouse. Write import chdb.datastore as pd and use the same pandas API, 10-100x faster. Supports 16+ data sources (MySQL, PostgreSQL, S3, MongoDB, Iceberg, Delta Lake, etc.) with cross-source joins.
Location: skills/chdb-datastore/ (opens in a new tab)
For agents: The skill activates when you analyze data with pandas-style syntax, speed up slow pandas code, query remote databases as DataFrames, or join data across different sources.
chdb SQL
In-process ClickHouse SQL for Python — run SQL queries on local files, remote databases, and cloud storage without a server. Covers chdb.query(), Session, DB-API 2.0, parametrized queries, UDFs, streaming, and all ClickHouse table functions.
Location: skills/chdb-sql/ (opens in a new tab)
For agents: The skill activates when you write SQL queries against files, use ClickHouse table functions, build stateful analytical pipelines, or use advanced ClickHouse SQL features.
Infra ClickHouse
Local and cloud workflows for running ClickHouse with clickhousectl (opens in a new tab). The top-level SKILL.md is a decision tree that routes to the right reference: ref/local.md (opens in a new tab) for local development (install ClickHouse, start a server, create schemas, seed data) and ref/cloud.md (opens in a new tab) for ClickHouse Cloud (authenticate, create a service, migrate schemas, connect an application). The local workflow hands off to cloud when going to production. Supersedes clickhousectl-local-dev and clickhousectl-cloud-deploy.
Location: skills/infra-clickhouse/ (opens in a new tab)
For agents: The skill activates when a user wants to build an application with ClickHouse, set up a local development environment, deploy to production, or manage a ClickHouse Cloud service.
Infra Postgres
Local and cloud workflows for running Postgres with clickhousectl (opens in a new tab). The top-level SKILL.md is a decision tree that routes to the right reference: ref/local.md (opens in a new tab) for local Docker-backed Postgres development (start, psql client, .env wiring, lifecycle) and ref/cloud.md (opens in a new tab) for managed ClickHouse Cloud Postgres services (beta) — authentication, service creation, connections and TLS, runtime configuration, read replicas, failover, and point-in-time restore. The local workflow hands off to cloud when going to production.
Location: skills/infra-postgres/ (opens in a new tab)
For agents: The skill activates when a user wants to set up a local Postgres for development, connect an application to Postgres, or create and manage a managed Postgres service in ClickHouse Cloud.
ClickStack OTel Collector
Step-by-step workflow for wiring an OpenTelemetry collector into a Managed ClickStack service on ClickHouse Cloud. Covers deploying a new local collector (Docker run or Docker Compose) or configuring an existing collector, creating a dedicated ingest SQL user, sending rich synthetic telemetry, and verifying the data is visible in ClickStack.
Location: skills/clickstack-otel-collector/ (opens in a new tab)
For agents: The skill activates when a user wants to connect an OpenTelemetry collector to a Managed ClickStack service, send telemetry (logs, traces, metrics) into ClickStack, or verify their observability data pipeline end-to-end.
Quick Start
After installation, your AI agent will reference these skills when:
- Creating new tables with
CREATE TABLE - Choosing
ORDER BY/PRIMARY KEYcolumns - Selecting data types for columns
- Optimizing slow queries
- Writing or tuning JOINs
- Designing data ingestion pipelines
- Handling updates or deletes
- Analyzing data with pandas-style DataStore API
- Querying files or databases with chdb SQL
- Joining data across different sources (MySQL + S3 + local files)
- Setting up a local ClickHouse development environment or deploying to ClickHouse Cloud with
clickhousectl - Setting up a local Postgres or a managed ClickHouse Cloud Postgres service with
clickhousectl - Wiring an OpenTelemetry collector into Managed ClickStack
Example prompts:
“Create a table for storing user events with fields for user_id, event_type, properties (JSON), and timestamp”
The agent will apply relevant ClickHouse best practices rules.
“Load this Parquet file and group by country, show top 10 by revenue”
The agent will use chdb DataStore or SQL to query the file directly.
“Join my MySQL customers table with this local orders.parquet file”
The agent will use chdb’s cross-source join capabilities.
Supported Agents
Skills are agent-agnostic—the same skill works across all supported AI coding assistants:
| Agent | Config Directory |
|---|---|
| Claude Code (opens in a new tab) | .claude/skills/ |
| Cursor (opens in a new tab) | .cursor/skills/ |
| Windsurf (opens in a new tab) | .windsurf/skills/ |
| GitHub Copilot (opens in a new tab) | .github/skills/ |
| Gemini CLI (opens in a new tab) | .gemini/skills/ |
| Cline (opens in a new tab) | .cline/skills/ |
| Codex (opens in a new tab) | .codex/skills/ |
| Goose (opens in a new tab) | .goose/skills/ |
| Roo Code (opens in a new tab) | .roo/skills/ |
| OpenHands (opens in a new tab) | .openhands/skills/ |
And 13 more including Amp, Kiro CLI, Trae, Zencoder, and others.
The installer detects which agents you have by checking for their configuration directories. If an agent isn’t listed, either install it first or create its config directory manually (e.g., mkdir -p ~/.cursor).
License
Apache 2.0 — see LICENSE (opens in a new tab) for details.
Colophon
How this issue was made- Source
- github.com/ClickHouse/agent-skills, branch
main, last pushed 6 August 2026. - Licence
- Apache-2.0 — the text of every chapter is reproduced unmodified, frontmatter included, under the upstream licence.
- Discovery
- 11 chapters found by walking the repository tree for
SKILL.md, not by matching a directory convention. One layout observed:skills/*/SKILL.md. - Issue colours
- Resolved from the awesome-design-md registry — hue 25°, chroma 0.190. Two accent tones are generated per issue and each is proven against its own ground before it ships: a single accent that passes AA on both light and dark paper is arithmetically impossible.
- Heading repairs
- 1 repair applied to the front matter so the document has one
h1and no skipped levels:- Shifted “17 headings” from h1 to h2 so the chapter title is the only h1.
- Spec compliance
- Every chapter satisfies the Agent Skills specification’s frontmatter rules.
- Images
- Images inside a chapter come from the upstream repository. Where the author gave no alternative text we mark the image decorative rather than inventing a description — a plausible caption we made up is worse than none for the reader who depends on it.
- Marketplace
- A plugin manifest is published at
.claude-plugin/marketplace.jsonby ClickHouse, declaring 8 plugins. It is read for editorial metadata only — never as the skill index, which is always the repository tree. - Signal
- Install counts come from skills.sh. They measure downloads, not quality, and an unranked repository is not an unread one.
- Agent surfaces
- The whole issue is available as one markdown document at
/ClickHouse/agent-skills.md, and each chapter at its own.mdURL. - Publication
- Set by Skills Docs from the source repository. Body text is Literata at the reader’s chosen size and measure; code is Geist Mono. Nothing on this page was written by us except this paragraph.