ClickHouse/agent-skills

The official Agent Skills for ClickHouse and ClickHouse Cloud

What it solves

This project provides a set of packaged instructions, known as "Agent Skills," to give AI coding agents (like Claude Code, Cursor, and Copilot) domain-specific expertise in using ClickHouse and chdb. It ensures that LLMs can apply official best practices for schema design, query optimization, and deployment workflows without the user having to manually prompt for them.

How it works

These skills follow the open specification at agentskills.io and are installed into the configuration directories of various AI agents. Once installed, the agent automatically references these rules and frameworks when it detects the user is working with ClickHouse or chdb, allowing it to provide more accurate, optimized, and official guidance on database operations.

Who it’s for

Developers and data engineers who use ClickHouse (open-source or Cloud) and chdb (in-process ClickHouse for Python) and want their AI assistants to write better SQL, optimize performance, and handle deployments correctly.

Highlights

  • Comprehensive Best Practices: Includes 28 rules covering critical areas like primary key selection, JOIN optimization, and data type selection.
  • Architecture Advisor: Provides decision frameworks for ingestion strategies, time-series partitioning, and real-time pre-aggregation.
  • Python Integration: Specialized skills for chdb DataStore (a pandas-compatible API) and chdb SQL for serverless querying.
  • Cross-Agent Compatibility: Works across a wide range of AI assistants including Claude Code, Cursor, Windsurf, and GitHub Copilot.
  • Deployment Workflows: Step-by-step guides for local development and cloud deployment using clickhousectl.
  • Node.js Troubleshooting: A dedicated guide for resolving common failure modes in the @clickhouse/client library.