ClickHouse Agent Skills

Install

npx skills add clickhouse/agent-skills

This is third-party code. Review the repository files before installing.

What it does

A skill set from the ClickHouse team that teaches the agent to design tables, pick sorting keys and data types, tune JOINs and set up ingestion. A separate skill guides architecture decisions for real-time workloads: insert strategies, partitioning, upserts and pre-aggregation. The chdb-sql and chdb-datastore skills cover in-process ClickHouse for Python, including a pandas-compatible API and queries over files and external databases. There are also workflows for clickhousectl (local development and ClickHouse Cloud), managed Postgres, wiring an OpenTelemetry collector into ClickStack, and troubleshooting the Node.js client.

Who it is for. For developers and analysts building schemas, queries and pipelines on ClickHouse or chDB.

Example request

Create a table for user events with user_id, event_type, JSON properties and a timestamp following ClickHouse best practices

Limitations

The skills provide knowledge and instructions but do not connect to a database themselves. Cloud workflows need a ClickHouse Cloud account, and managed Postgres is in beta. chDB runs on macOS and Linux with Python 3.9+.

How to disable. Delete the skill folders from your agent's skills directory or uninstall the plugin via /plugin.

Security check

• The skills are instructions and references; cloud workflows suggest clickhousectl commands the agent runs with your approval

README in short

The README lists the repository's skills: prioritized rules for schemas, queries and ingestion, an architecture advisor, chDB SQL and DataStore, clickhousectl workflows for ClickHouse and Postgres, OpenTelemetry setup for ClickStack and Node.js client troubleshooting. Install with npx skills add or with clickhousectl skills. The skills follow the agentskills.io spec and work in Claude Code, Cursor, Windsurf, Copilot, Gemini CLI, Codex and other agents. Apache 2.0 licensed.

SKILL.md

---
name: chdb-datastore
description: >-
  Use when the user has tabular data (pandas DataFrame, parquet, csv,
  Arrow, json) and wants to filter, group, aggregate, join, or speed
  up slow pandas. Provides chDB DataStore — same pandas API,
  ClickHouse engine underneath. Also handles reading from S3, MySQL,
  PostgreSQL, MongoDB, ClickHouse Cloud, Iceberg, Delta Lake as
  DataFrames and joining across sources.
  TRIGGER when: user mentions DataFrame, parquet, csv, "fast pandas",
  "speed up pandas", or cross-source DataFrame joins; user imports
  `chdb.datastore` or `from datastore import DataStore`.
  SKIP this skill for raw SQL syntax (use chdb-sql instead),
  ClickHouse server administration, or non-Python DataStore API work.
license: Apache-2.0
compatibility: Requires Python 3.9+, macOS or Linux. pip install chdb.
metadata:
  author: chdb-io
  version: "4.1"
  homepage: https://clickhouse.com/docs/chdb
---

# chdb DataStore — It's Just Faster Pandas

## The Key Insight

```python
# Change this:
import pandas as pd
# To this:
import chdb.datastore as pd
# Everything else stays the same.
```

DataStore is a **lazy, ClickHouse-backed pandas replacement**. Your existing pandas code works unchanged — but operations compile to optimized SQL and execute only when results are needed (e.g., `print()`, `len()`, iteration).

```bash
pip install chdb
```

Related