Skip to content
Back to search

clickhouse-agent-skills

MarketplaceWorks with Claude CodeGitHubIncomplete

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/clickhouse--agent-skills/badge.svg)](/listings/clickhouse--agent-skills)

HTML

<a href="/listings/clickhouse--agent-skills"><img src="/api/listings/clickhouse--agent-skills/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npx

npx skills add clickhouse/agent-skills

The CLI auto-detects installed agents and prompts you to select where to install.

clickhousectl

Use the ClickHouse CLI [`clickhousectl`](https://github.com/ClickHouse/clickhousectl) to install the agent skills:

clickhousectl skills

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 175 lines
  1. {
  2. "name": "clickhouse-agent-skills",
  3. "owner": {
  4. "name": "ClickHouse"
  5. },
  6. "metadata": {
  7. "description": "Official ClickHouse best practices for Claude Code",
  8. "version": "0.5.0"
  9. },
  10. "plugins": [
  11. {
  12. "name": "clickhouse-best-practices",
  13. "source": "./",
  14. "description": "36 best practice rules for ClickHouse schema design, query optimization, native full-text search, and data ingestion — prioritized by impact",
  15. "version": "0.5.0",
  16. "author": {
  17. "name": "ClickHouse Inc"
  18. },
  19. "homepage": "https://clickhouse.ai",
  20. "repository": "https://github.com/ClickHouse/agent-skills",
  21. "license": "Apache-2.0",
  22. "keywords": [
  23. "clickhouse",
  24. "database",
  25. "query-optimization",
  26. "schema-design",
  27. "best-practices"
  28. ],
  29. "category": "database"
  30. },
  31. {
  32. "name": "clickhouse-architecture-advisor",
  33. "source": "./skills/clickhouse-architecture-advisor/",
  34. "description": "Workload-aware architecture decision skill for ClickHouse — ingestion strategies, partitioning, enrichment, upsert patterns, and pre-aggregation with explicit official/derived/field provenance",
  35. "version": "0.1.0",
  36. "author": {
  37. "name": "ClickHouse Inc"
  38. },
  39. "homepage": "https://clickhouse.ai",
  40. "repository": "https://github.com/ClickHouse/agent-skills",
  41. "license": "Apache-2.0",
  42. "keywords": [
  43. "clickhouse",
  44. "database",
  45. "architecture",
  46. "design",
  47. "advisor"
  48. ],
  49. "category": "database"
  50. },
  51. {
  52. "name": "clickhouse-js-node-troubleshooting",
  53. "source": "./skills/clickhouse-js-node-troubleshooting/",
  54. "description": "Troubleshooting guide for the ClickHouse Node.js client (@clickhouse/client) — socket hang-up/ECONNRESET, Keep-Alive, data type mismatches, read-only users, proxy/pathname URLs, TLS, compression, logging, and query parameters",
  55. "version": "0.1.0",
  56. "author": {
  57. "name": "ClickHouse Inc"
  58. },
  59. "homepage": "https://clickhouse.ai",
  60. "repository": "https://github.com/ClickHouse/agent-skills",
  61. "license": "Apache-2.0",
  62. "keywords": [
  63. "clickhouse",
  64. "nodejs",
  65. "javascript",
  66. "client",
  67. "troubleshooting"
  68. ],
  69. "category": "database"
  70. },
  71. {
  72. "name": "chdb-datastore",
  73. "source": "./skills/chdb-datastore/",
  74. "description": "Pandas-compatible DataStore API for chDB — same pandas API backed by ClickHouse for 10-100x faster filter/group/aggregate/join, with built-in readers for S3, MySQL, PostgreSQL, MongoDB, ClickHouse Cloud, Iceberg, and Delta Lake and cross-source DataFrame joins",
  75. "version": "4.1.0",
  76. "author": {
  77. "name": "ClickHouse Inc"
  78. },
  79. "homepage": "https://clickhouse.ai",
  80. "repository": "https://github.com/ClickHouse/agent-skills",
  81. "license": "Apache-2.0",
  82. "keywords": [
  83. "chdb",
  84. "clickhouse",
  85. "pandas",
  86. "dataframe",
  87. "parquet",
  88. "analytics"
  89. ],
  90. "category": "database"
  91. },
  92. {
  93. "name": "chdb-sql",
  94. "source": "./skills/chdb-sql/",
  95. "description": "Embedded ClickHouse SQL engine for Python via chDB — run analytical SQL on parquet/csv/json files, URLs, S3, and remote databases (Postgres, MySQL, MongoDB, ClickHouse Cloud, Iceberg, Delta Lake) with Session for stateful pipelines, parametrized queries, UDFs, and cross-source joins",
  96. "version": "4.1.0",
  97. "author": {
  98. "name": "ClickHouse Inc"
  99. },
  100. "homepage": "https://clickhouse.ai",
  101. "repository": "https://github.com/ClickHouse/agent-skills",
  102. "license": "Apache-2.0",
  103. "keywords": [
  104. "chdb",
  105. "clickhouse",
  106. "sql",
  107. "analytics",
  108. "parquet",
  109. "embedded"
  110. ],
  111. "category": "database"
  112. },
  113. {
  114. "name": "infra-clickhouse",
  115. "source": "./skills/infra-clickhouse/",
  116. "description": "Local and cloud workflows for running ClickHouse with clickhousectl — local development (install ClickHouse, start a server, create schemas, seed data) and ClickHouse Cloud deployment (authenticate, create a service, migrate schemas, connect an application), with a decision tree routing between them",
  117. "version": "0.4.0",
  118. "author": {
  119. "name": "ClickHouse Inc"
  120. },
  121. "homepage": "https://clickhouse.ai",
  122. "repository": "https://github.com/ClickHouse/agent-skills",
  123. "license": "Apache-2.0",
  124. "keywords": [
  125. "clickhouse",
  126. "clickhousectl",
  127. "database",
  128. "local-development",
  129. "cloud",
  130. "deployment"
  131. ],
  132. "category": "database"
  133. },
  134. {
  135. "name": "infra-postgres",
  136. "source": "./skills/infra-postgres/",
  137. "description": "Local and cloud workflows for running Postgres with clickhousectl — local Docker-backed Postgres for development (start, psql client, .env wiring, lifecycle) and managed ClickHouse Cloud Postgres services, beta (authentication, service creation, connections and TLS, runtime config, read replicas, failover, point-in-time restore), with a decision tree routing between them",
  138. "version": "0.3.0",
  139. "author": {
  140. "name": "ClickHouse Inc"
  141. },
  142. "homepage": "https://clickhouse.ai",
  143. "repository": "https://github.com/ClickHouse/agent-skills",
  144. "license": "Apache-2.0",
  145. "keywords": [
  146. "clickhouse",
  147. "clickhousectl",
  148. "postgres",
  149. "database",
  150. "cloud"
  151. ],
  152. "category": "database"
  153. },
  154. {
  155. "name": "clickstack-otel-collector",
  156. "source": "./skills/clickstack-otel-collector/",
  157. "description": "Step-by-step workflow for wiring an OpenTelemetry collector into a Managed ClickStack service on ClickHouse Cloud — deploying a new local collector or configuring an existing one, creating a dedicated ingest user, sending synthetic telemetry, and verifying it in ClickStack",
  158. "version": "0.6.0",
  159. "author": {
  160. "name": "ClickHouse Inc"
  161. },
  162. "homepage": "https://clickhouse.ai",
  163. "repository": "https://github.com/ClickHouse/agent-skills",
  164. "license": "Apache-2.0",
  165. "keywords": [
  166. "clickhouse",
  167. "clickstack",
  168. "opentelemetry",
  169. "observability",
  170. "collector"
  171. ],
  172. "category": "database"
  173. }
  174. ]
  175. }
README.md · README · 181 lines
  1. # ClickHouse Agent Skills
  2. The official Agent Skills for [ClickHouse](https://clickhouse.com/). These skills help LLMs and agents to adopt best practices when working with ClickHouse and [chdb](https://clickhouse.com/docs/chdb) (in-process ClickHouse for Python).
  3. You can use these skills with open-source ClickHouse and managed ClickHouse Cloud. [Try ClickHouse Cloud with $300 in free credits](https://clickhouse.com/cloud?utm_medium=github&utm_source=github&utm_ref=agent-skills).
  4. ## Installation
  5. ### npx
  6. ```bash
  7. npx skills add clickhouse/agent-skills
  8. ```
  9. The CLI auto-detects installed agents and prompts you to select where to install.
  10. ### clickhousectl
  11. Use the ClickHouse CLI [`clickhousectl`](https://github.com/ClickHouse/clickhousectl) to install the agent skills:
  12. ```bash
  13. clickhousectl skills
  14. ```
  15. ## What is this?
  16. 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.
  17. 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.
  18. Skills follow the open specification at [agentskills.io](https://agentskills.io).
  19. ## Available Skills
  20. ### ClickHouse Best Practices
  21. **36 rules** covering schema design, query optimization, native full-text search, and data ingestion—prioritized by impact.
  22. | Category | Rules | Impact |
  23. |----------|-------|--------|
  24. | Primary Key Selection | 4 | CRITICAL |
  25. | Data Type Selection | 5 | CRITICAL |
  26. | JOIN Optimization | 5 | CRITICAL |
  27. | Insert Batching | 1 | CRITICAL |
  28. | Mutation Avoidance | 2 | CRITICAL |
  29. | Partitioning Strategy | 4 | HIGH |
  30. | Secondary and Text Indices | 6 | HIGH |
  31. | Materialized Views | 2 | HIGH |
  32. | Async Inserts | 2 | HIGH |
  33. | OPTIMIZE Avoidance | 1 | HIGH |
  34. | JSON Usage | 1 | MEDIUM |
  35. | Agent Connectivity, Discovery, and Safety | 3 | CRITICAL / HIGH |
  36. **Location:** [`skills/clickhouse-best-practices/`](./skills/clickhouse-best-practices/)
  37. **For humans:** Read [SKILL.md](./skills/clickhouse-best-practices/SKILL.md) for an overview, or [AGENTS.md](./skills/clickhouse-best-practices/AGENTS.md) for the complete compiled guide.
  38. **For agents:** The skill activates automatically when you work with ClickHouse—creating tables, writing queries, or designing data pipelines.
  39. ### ClickHouse Architecture Advisor
  40. **5 decision frameworks** covering workload-aware architecture decisions for real-time ClickHouse deployments.
  41. | Decision Area | Impact |
  42. |---------------|--------|
  43. | Ingestion Strategy | CRITICAL |
  44. | Join & Enrichment Patterns | CRITICAL |
  45. | Late-Arriving Data & Upserts | CRITICAL |
  46. | Time-Series Partitioning | HIGH |
  47. | Real-Time Pre-Aggregation | HIGH |
  48. Complements `clickhouse-best-practices` by answering *when*, *why*, and *how* — not just *what*. All recommendations are explicitly classified as `official`, `derived`, or `field` guidance.
  49. **Location:** [`skills/clickhouse-architecture-advisor/`](./skills/clickhouse-architecture-advisor/)
  50. **For humans:** Read [SKILL.md](./skills/clickhouse-architecture-advisor/SKILL.md) for an overview, or [AGENTS.md](./skills/clickhouse-architecture-advisor/AGENTS.md) for the compiled guide.
  51. **For agents:** The skill activates during architecture design sessions — when choosing ingestion patterns, designing time-series schemas, selecting enrichment strategies, or handling mutable state.
  52. ### ClickHouse JS Node Troubleshooting
  53. **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.
  54. **Location:** [`skills/clickhouse-js-node-troubleshooting/`](./skills/clickhouse-js-node-troubleshooting/)
  55. **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.
  56. ### chdb DataStore
  57. **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.
  58. **Location:** [`skills/chdb-datastore/`](./skills/chdb-datastore/)
  59. **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.
  60. ### chdb SQL
  61. **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.
  62. **Location:** [`skills/chdb-sql/`](./skills/chdb-sql/)
  63. **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.
  64. ### Infra ClickHouse
  65. **Local and cloud workflows** for running ClickHouse with [`clickhousectl`](https://github.com/ClickHouse/clickhousectl). The top-level `SKILL.md` is a decision tree that routes to the right reference: [`ref/local.md`](./skills/infra-clickhouse/ref/local.md) for local development (install ClickHouse, start a server, create schemas, seed data) and [`ref/cloud.md`](./skills/infra-clickhouse/ref/cloud.md) 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`.
  66. **Location:** [`skills/infra-clickhouse/`](./skills/infra-clickhouse/)
  67. **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.
  68. ### Infra Postgres
  69. **Local and cloud workflows** for running Postgres with [`clickhousectl`](https://github.com/ClickHouse/clickhousectl). The top-level `SKILL.md` is a decision tree that routes to the right reference: [`ref/local.md`](./skills/infra-postgres/ref/local.md) for local Docker-backed Postgres development (start, psql client, `.env` wiring, lifecycle) and [`ref/cloud.md`](./skills/infra-postgres/ref/cloud.md) for managed ClickHouse Cloud Postgres services (beta) — authentication, service creation, connections and TLS, runtime configuration, read replicas, failover, and point-in-time restore. [`ref/migrate.md`](./skills/infra-postgres/ref/migrate.md) migrates an existing Postgres (Neon, Supabase, RDS, ...) into ClickHouse Cloud Postgres with `pg_dump`/`pg_restore`. The local workflow hands off to cloud when going to production.
  70. **Location:** [`skills/infra-postgres/`](./skills/infra-postgres/)
  71. **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.
  72. ### ClickStack OTel Collector
  73. **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.
  74. **Location:** [`skills/clickstack-otel-collector/`](./skills/clickstack-otel-collector/)
  75. **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.
  76. ## Quick Start
  77. After installation, your AI agent will reference these skills when:
  78. - Creating new tables with `CREATE TABLE`
  79. - Choosing `ORDER BY` / `PRIMARY KEY` columns
  80. - Selecting data types for columns
  81. - Optimizing slow queries
  82. - Writing or tuning JOINs
  83. - Designing data ingestion pipelines
  84. - Handling updates or deletes
  85. - Analyzing data with pandas-style DataStore API
  86. - Querying files or databases with chdb SQL
  87. - Joining data across different sources (MySQL + S3 + local files)
  88. - Setting up a local ClickHouse development environment or deploying to ClickHouse Cloud with `clickhousectl`
  89. - Setting up a local Postgres or a managed ClickHouse Cloud Postgres service with `clickhousectl`
  90. - Wiring an OpenTelemetry collector into Managed ClickStack
  91. Example prompts:
  92. > "Create a table for storing user events with fields for user_id, event_type, properties (JSON), and timestamp"
  93. The agent will apply relevant ClickHouse best practices rules.
  94. > "Load this Parquet file and group by country, show top 10 by revenue"
  95. The agent will use chdb DataStore or SQL to query the file directly.
  96. > "Join my MySQL customers table with this local orders.parquet file"
  97. The agent will use chdb's cross-source join capabilities.
  98. ## Supported Agents
  99. Skills are **agent-agnostic**—the same skill works across all supported AI coding assistants:
  100. | Agent | Config Directory |
  101. |-------|------------------|
  102. | [Claude Code](https://claude.ai/code) | `.claude/skills/` |
  103. | [Cursor](https://cursor.sh) | `.cursor/skills/` |
  104. | [Windsurf](https://codeium.com/windsurf) | `.windsurf/skills/` |
  105. | [GitHub Copilot](https://github.com/features/copilot) | `.github/skills/` |
  106. | [Gemini CLI](https://github.com/google-gemini/gemini-cli) | `.gemini/skills/` |
  107. | [Cline](https://github.com/cline/cline) | `.cline/skills/` |
  108. | [Codex](https://openai.com/codex) | `.codex/skills/` |
  109. | [Goose](https://github.com/block/goose) | `.goose/skills/` |
  110. | [Roo Code](https://roo.ai) | `.roo/skills/` |
  111. | [OpenHands](https://github.com/All-Hands-AI/OpenHands) | `.openhands/skills/` |
  112. And 13 more including Amp, Kiro CLI, Trae, Zencoder, and others.
  113. 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`).
  114. ## License
  115. Apache 2.0 — see [LICENSE](./LICENSE) for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.