ClickHouse Agent Skills

What it is

ClickHouse Agent Skills is ClickHouse’s own pack of skills for coding agents. The README says they help an agent follow best practice with ClickHouse and with chdb, the in-process version for Python. The skills folder holds eleven skills. The README describes eight. They are rules for tables and queries, an architecture advisor, a Node.js troubleshooter, two chdb skills, and three that set up ClickHouse, Postgres and an OpenTelemetry collector with the clickhousectl command line.

1. You install the pack with one npx line
2. The installer asks which agent gets the skills
3. Your agent loads a skill when the task matches
4. It reads the rules or runs clickhousectl and chdb
5. You get a cited review or a working setup

Who it suits

Developers who build on ClickHouse, and analysts who use chdb from Python. It helps most when an agent does the typing while you design a table, tune a slow query, load data or set up a local or cloud service. Skip it if you do not use ClickHouse or chdb.

Where to use it

The README says the same skills work in every agent its installer supports. The installer finds each agent by its config folder.

• Claude Code and Codex: .claude/skills/ and .codex/skills/
• Cursor, Windsurf and GitHub Copilot: .cursor/skills/, .windsurf/skills/ and .github/skills/
• Gemini CLI, Cline, Goose, Roo Code and OpenHands: five more in the README’s table
• More agents, among them Amp, Kiro CLI, Trae and Zencoder, which the README names without folders

How to set it up

You run one installer line, and the installer asks which agent gets the skills. Get it saves a zip of Mindket’s setup notes in your downloads folder, with a page for each route.

1. Install the pack. Run the npx line and answer the installer’s prompts.
2. Check that the skills landed. Look for folders such as clickhouse-best-practices in your agent’s skills folder.
3. Try it on a table. Ask your agent for a ClickHouse design or review and watch for the rules it cites.

npx skills add clickhouse/agent-skills

The README says the CLI auto-detects installed agents and prompts you to select where to install. If your agent is not found, install it first or create its config folder by hand. The README’s own example is mkdir -p ~/.cursor for Cursor. A second route uses ClickHouse’s command line tool. Install that tool first: the infra skills do it with curl -fsSL https://clickhouse.com/cli | sh. Then this line installs the skills:

clickhousectl skills

How to use it

Work as you normally would. Each skill loads when its task comes up, so there is no command to type. Your agent reads the rules or runs the tools a skill names.

Example

You are about to create a table for page views and want it checked first.

Review this table for ClickHouse best practices: CREATE TABLE events (user_id String, ts DateTime, payload String) ENGINE = MergeTree ORDER BY ts

The agent reads the schema rules, then answers with the rules it checked, the problems it found with a fix for each, and a ranked list of changes.

Each finding names its rule, such as schema-types-native-types, so you can open the rule file and read the reason yourself.

For newcomers and experts

If you are new. ClickHouse is a column-oriented database, and the best-practices skill warns that habits from a general database can mislead you here. Its first listed rule says a table’s ORDER BY is fixed once the table exists. Start with the best-practices skill and the local setup in infra-clickhouse, which needs no cloud account.

For experts. The best-practices rule files carry prefixes by topic: schema-pk, schema-types, schema-partition, schema-json, query-join, query-index, query-mv, insert and agent. The README ranks primary keys, data types, joins, insert batching and mutation avoidance as critical. The skill file sets a workflow for every agent session that queries ClickHouse: connect, look up the schema, plan, run with LIMIT and timeouts, and recover by narrowing filters. For the connection, its agent-connect-mcp rule gives ClickHouse Cloud’s hosted MCP server, which it says uses OAuth and is read-only:

claude mcp add --transport http clickhouse-cloud https://mcp.clickhouse.cloud/mcp

The architecture advisor adds a label to every recommendation. Official means ClickHouse’s docs say it. Derived means it follows from documented behavior. Field means experience, and the skill says to flag it as a heuristic.

Good to know

The skills are text that your agent follows, and several have it run commands.

• Count: the folder holds eleven skills and the README describes eight. The others are clickhouse-js-node-coding, clickhouse-js-node-rowbinary and clickhouse-managed-postgres-rca
• Rules: the README counts 28 best-practices rules and the skill file counts 31, since it adds three for agents
• Cloud costs: when a request does not say local or cloud, the infra skills default to local and ask before creating anything in the cloud, since cloud services cost money
• Cloud keys: any cloud write, such as creating a service, needs an API key, since an OAuth login is read-only. The skill asks for a key with the Admin role, and you log in from a second terminal, so the secret stays out of the chat
• Open by default: the infra skill’s cloud steps note that a service created without an IP allow list is open to all addresses
• ClickStack: its skill creates a SQL user, writes secrets to a private env file and starts a collector. Its cleanup runs only if you ask
• Postgres RCA: it recommends a fix and applies none. You supply the API key pair, the organization id and the service id
• Maker: ClickHouse Inc, Apache 2.0. The two chdb skills name chdb-io as their author. The NOTICE credits Vercel’s Agent Skills project for four build files