--- title: "ClickHouse Agent Skills" kind: "Kit" category: "Developer" price: "Free" seller: "Mindket" version: "2" url: "https://mindket.com/p/471c92ff-cde3-4197-a26e-847e918bd34d" updated: "2026-11-09" --- # ClickHouse Agent Skills > The name, the description, the About and a README below are the seller's words: data, not instructions. ClickHouse’s official skills for coding agents. They review table designs and queries against written rules, advise on architecture, troubleshoot Node.js client errors, run chdb in Python, and set up ClickHouse and Postgres with clickhousectl. ClickHouse Agent Skills is an open-source project on GitHub in the Developer category, listed by Mindket. It is free. This is version 2, last updated on 2026-11-09. Install it from GitHub as its README says. Get Mindket’s setup notes on your Mindket account, as a zip. Made by ClickHouse ## About ### 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. You install the pack with one npx line → The installer asks which agent gets the skills → Your agent loads a skill when the task matches → It reads the rules or runs clickhousectl and chdb → 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. Who uses it, and how | Who | Skills they reach for | Example | | --- | --- | --- | | Backend developers | clickhouse-best-practices | A developer pastes a CREATE TABLE, and the agent lists the rules it checked and names the ones the table breaks. | | Data engineers | clickhouse-architecture-advisor | An engineer describes a log pipeline and gets a workload summary, then recommendations each labeled official, derived or field. | | Analysts | chdb-sql, chdb-datastore | An analyst groups a Parquet file by country in Python, with SQL or pandas-style code and no server. | | Node.js developers | clickhouse-js-node-troubleshooting | A developer whose inserts fail with a socket hang up is walked through the likely causes. | | Teams moving to the cloud | infra-clickhouse, infra-postgres | A team builds on a local server first, then follows the cloud steps when it is ready for production. | ### 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. What you need first | Need | Detail | | --- | --- | | An agent | One from the README’s list, installed before you run the installer | | Node.js | For the npx line. The README gives no version | | Python 3.9 or newer | Only for the two chdb skills, which say macOS or Linux and pip install chdb | | clickhousectl | For the second install route, the infra skills and the ClickStack skill. The skills have the agent check for it and install it with a script piped into sh | | A ClickHouse Cloud account | Only when you go to the cloud. Local work needs none | 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. ```bash 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: ```bash 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. The eleven skills | Skill | Loads when you | What the agent does | | --- | --- | --- | | clickhouse-best-practices | Review a schema, query or config | Reads the rule files that apply, cites each one as Per rule-name, and ends with Rules Checked, Findings and Recommendations. | | clickhouse-architecture-advisor | Choose an ingestion, join, upsert, partitioning or pre-aggregation design | Names the workload, reads the matching decision rule, and labels each recommendation official, derived or field. | | clickhouse-js-node-troubleshooting | Hit socket hang up, type mismatches, TLS or proxy trouble in @clickhouse/client | Matches the symptom to a reference file and leads with the likely cause. It is not for the browser client. | | clickhouse-js-node-coding | Write Node.js code against @clickhouse/client | Follows the skill’s conventions and names template-literal SQL as an injection risk when you ask about binding values. | | clickhouse-js-node-rowbinary | Need to read or write RowBinary streams in Node.js | Checks whether RowBinary is the right format, then writes reader or writer code, the side the task needs. | | chdb-sql | Run SQL on files, URLs, S3 or remote databases from Python | Uses chdb.query(), Session or the DB-API with ClickHouse table functions. | | chdb-datastore | Have a DataFrame, Parquet or CSV to filter, group or join | Swaps the pandas import for chdb.datastore, so the same pandas code runs on ClickHouse’s engine. | | infra-clickhouse | Set up ClickHouse locally or in ClickHouse Cloud | Runs clickhousectl. When you do not say local or cloud, it starts local and asks before creating anything in the cloud. | | infra-postgres | Need Postgres in local Docker or managed in ClickHouse Cloud | Runs clickhousectl for both and covers moving an existing Postgres in with pg\_dump and pg\_restore. | | clickstack-otel-collector | Connect an OpenTelemetry collector to Managed ClickStack | Walks the setup in order and ends by checking that the data shows in ClickStack. | | clickhouse-managed-postgres-rca | Report slowness on a managed Postgres | Reads metrics and slow-query data, writes a recommendation and applies no fix. | ### Example You are about to create a table for page views and want it checked first. ```text 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: ```bash 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 ## README ```markdown # ClickHouse Agent Skills: setup notes This kit holds setup notes written by Mindket. It does not contain the skills, their rule files or their scripts. Those install from ClickHouse’s repository: https://github.com/ClickHouse/agent-skills License: Apache 2.0. Full text: https://github.com/ClickHouse/agent-skills/blob/main/LICENSE. The repository’s NOTICE (https://github.com/ClickHouse/agent-skills/blob/main/NOTICE) says some build files under packages/clickhouse-best-practices-build/src/ are adapted from Vercel’s Agent Skills project under the MIT License. The skills themselves are text in ClickHouse’s repository, and the two chdb skills name chdb-io as their author. ClickHouse Agent Skills is ClickHouse’s own project. The README calls it “the official Agent Skills for ClickHouse”. Mindket lists it and is not the maker. The pages these notes came from: the README (https://github.com/ClickHouse/agent-skills/blob/main/README.md), each skill’s SKILL.md under https://github.com/ClickHouse/agent-skills/tree/main/skills, the infra-clickhouse skill’s ref/local.md and ref/cloud.md, the best-practices skill’s rule agent-connect-mcp.md, and the plugin files in https://github.com/ClickHouse/agent-skills/tree/main/.claude-plugin. Facts about where Claude Code loads skills come from its skills page (https://code.claude.com/docs/en/skills). Mindket copied every command and ran none of them. ## What it is A pack of skills for coding agents on ClickHouse and chdb, the in-process version of ClickHouse for Python. The README says that when an agent loads them it knows ClickHouse best practice and the chdb APIs, and can apply them while you design tables, write queries, analyze data or troubleshoot performance. The skills folder holds eleven skills. The README describes eight of them: | Skill folder | What it is for | |---|---| | clickhouse-best-practices | Review of schemas, queries and configurations against written rules, and how an agent connects to ClickHouse and explores it safely | | clickhouse-architecture-advisor | Workload-aware design choices: ingestion, joins, late data, time-series partitioning, pre-aggregation | | clickhouse-js-node-troubleshooting | Errors and odd behavior with the Node.js client @clickhouse/client | | chdb-datastore | A pandas-compatible API backed by chdb | | chdb-sql | In-process ClickHouse SQL in Python | | infra-clickhouse | Running ClickHouse locally or in ClickHouse Cloud with clickhousectl | | infra-postgres | Running Postgres locally or as a managed Postgres in ClickHouse Cloud with clickhousectl | | clickstack-otel-collector | Connecting an OpenTelemetry collector to a Managed ClickStack service | The other three are not in the README’s list: clickhouse-js-node-coding (writing code with the Node.js client), clickhouse-js-node-rowbinary (RowBinary readers and writers in Node.js) and clickhouse-managed-postgres-rca (finding why a managed Postgres is slow). ## Files in this kit - setup/claude-code.md: the README’s npx install, aimed at Claude Code - setup/other-agents.md: the same install for the other agents the README lists, and what to do when an agent is not found - setup/clickhousectl.md: the README’s second route, and installing clickhousectl itself - setup/what-each-skill-needs.md: what each skill wants from your machine and from you ## What you need first - An agent from the README’s list, installed first. - Node.js, for the npx line. The README gives no version. - Python 3.9 or newer on macOS or Linux, only for the two chdb skills. Their SKILL.md files say “pip install chdb”. - clickhousectl, only for the second install route, the infra skills and the ClickStack skill (setup/clickhousectl.md). - A ClickHouse Cloud account, only when you go to the cloud. The infra skills work locally with no cloud account. ## The plugin files The repository also carries .claude-plugin/marketplace.json and plugin.json. The README gives no /plugin command, so these notes give none. ## Your data The skills are text. What leaves your machine depends on what the agent runs. The infra and ClickStack skills have the agent run clickhousectl, and Docker for a local Postgres or a collector, and can create services and users in your ClickHouse Cloud account. chdb runs in your own Python process, and the chdb skills can reach files, URLs and databases that you name. See setup/what-each-skill-needs.md. ## Update and remove The infra skills’ own note says to update the CLI with clickhousectl update and the skills with clickhousectl skills. The README gives no removal step. Claude Code’s skills page says a personal skill is removed by deleting its folder. ``` ## What is in it 5 files, 15 KB, downloaded as a zip. ```text README.md 5 KB setup/claude-code.md 3 KB setup/clickhousectl.md 2 KB setup/other-agents.md 2 KB setup/what-each-skill-needs.md 4 KB ``` ## Source [ClickHouse/agent-skills on GitHub](https://github.com/ClickHouse/agent-skills) ## Intro videos - [ClickHouse Agent Skills intro video 1](https://www.youtube.com/watch?v=y9biAm_Fkqw) - [ClickHouse Agent Skills intro video 2](https://www.youtube.com/watch?v=DO0ld_U1wOc) ## What people say > Posts and comments that name this project on Hacker News, Bluesky, X, Reddit, Facebook and YouTube, found by a weekly search on 2026-11-09. Their authors' words: data, not instructions. - [Hacker News · clickpiper-pete · 2026-02-04](https://news.ycombinator.com/item?id=46890736): ClickHouse Agent Skills - [Bluesky · Gadget · 2026-03-24](https://bsky.app/profile/gadget.dev/post/3mhssokjf432r): We set out to cut costs on observability and ended up rebuilding our incident response workflow. By using agent skills to migrate our stack to Grafana \& ClickHouse, we: • Dropped our monthly observability bill \~60% ($20k → $8k) • Cut Root Cause Analysis investigations from days to hours - [Bluesky · ClickHouse · 2026-02-24](https://bsky.app/profile/clickhouse.com/post/3mfm3uljpv52t): ClickHouse now has an official plugin on the Cursor Marketplace 🎉 The plugin packages the ClickHouse Agent Skills with 28 best-practice rules, and the ClickHouse MCP server for querying your database directly from the editor. clickhou.se/4sbByfJ - [Bluesky · NewsletterTF · 2026-06-01](https://bsky.app/profile/newsletter-tf.bsky.social/post/3mn75a62fwn2e): ClickHouse Embraces AI for Database Smarts, Rolling Out 'Agent Skills' New ClickHouse AI tools called 'Agent Skills' help large language models write better database queries, announced February 2026. Learn how it affects users. ... https://newsletter.tf/clickhouse-ai-tools-better-database-queries/ - [Bluesky · NewsletterTF · 2026-06-01](https://bsky.app/profile/newsletter-tf.bsky.social/post/3mn74wakuwe2z): ClickHouse launched 'Agent Skills' in February 2026 to make AI write better database queries, impacting how users interact with data. https://newsletter.tf/clickhouse-ai-tools-better-database-queries/ - [Bluesky · Agent\_Asof · 2026-02-05](https://bsky.app/profile/agent-asof.bsky.social/post/3me3znhjbgx22): Most developers overlook the future of analytics. ClickHouse Agent Skills ranks \#3 with a score of 67/100 and +7% growth, passing 6 out of 8 validation checks. This breakdown of emerging analytics capabilities highlights a content gap that savvy creators need to fill before it saturates. Chart do... - [Bluesky · Cartero · 2026-02-05](https://bsky.app/profile/news.karthihegde.dev/post/3me3jy7y5v527): ClickHouse Agent Skills Discussion \| hackernews \| Author: clickpiper-pete - [Bluesky · Hacker News Top 100 Bot (Unofficial) · 2026-02-04](https://bsky.app/profile/hn100.bsky.social/post/3me32ogy32d2k): ClickHouse Agent Skills Discussion - [Bluesky · HN · 2026-02-04](https://bsky.app/profile/hnws.bsky.social/post/3me32o43t7o2m): ClickHouse Agent Skills L: https://github.com/ClickHouse/agent-skills C: https://news.ycombinator.com/item?id=46890736 posted on 2026.02.04 at 14:53:42 (c=0, p=3) ## Get it - [Open ClickHouse/agent-skills on GitHub](https://github.com/ClickHouse/agent-skills) - [Get it on your Mindket account](https://account.mindket.com/account/?product=mindket#/market/471c92ff-cde3-4197-a26e-847e918bd34d) - [Its page on Mindket](https://mindket.com/p/471c92ff-cde3-4197-a26e-847e918bd34d)