ClickHouse Skills

Use when a user wants to wire an OpenTelemetry collector into a Managed ClickStack service on ClickHouse Cloud, either by deploying a new local collector (Docker run or Docker Compose) or by configuring their own existing collector, then send rich synthetic telemetry and verify it is visible in ClickStack.

Review a Pull Request for correctness, safety, performance, and compliance. Use when the user wants to review a PR or diff.

Analyze a jemalloc (or other) allocation profile in collapsed stack format. Use when the user wants to analyze memory allocations, find top allocators, or understand memory usage patterns from a .collapsed profile file.

Bisect a ClickHouse regression using pre-built master binaries from CI. Use when the user wants to find the commit that introduced a bug.

Generate PR descriptions for ClickHouse/ClickHouse that match maintainer expectations. Use when creating or updating PR descriptions.

Audit open "flaky test" GitHub issues and close those whose tests are no longer failing on master. Cross-references CI history from play.clickhouse.com with git log to attribute fixes.

Continue work on an existing PR - resolve conflicts, fix CI failures, address reviewer feedback, and push updates. Use when the user wants to pick up and advance a pull request.

Profile a ClickHouse query using the sampling query profiler and system.trace_log. Use when the user wants to find CPU hotspots, analyze where time is spent in a query, or investigate performance bottlenecks.

Create test datasets (hits, visits, tpcds, tpch) from standard scripts. Ensures the server is running first.

Create a ClickHouse git worktree with submodules hardlinked from the main repo. Use when the user wants to create a new worktree for ClickHouse development.

Extract the inner ELF from a ClickHouse self-extracting `clickhouse` binary, including when its architecture differs from the host (e.g. to load an aarch64 CI core dump on an x86 workstation). Use when gdb/lldb needs real symbols from a downloaded CI/release binary, or when self-extraction by running the binary is not possible because of an architecture mismatch.

Edit an auto-generated ClickHouse release changelog into the form that gets committed to CHANGELOG.md. Use when the user has the output of `utils/changelog/changelog.py` and wants it cleaned up and re-categorized for a release.

Fix the "CH Inc sync" job in a pull request. Diagnoses the failure as one of three types — conflicts found, build failed, or tests failed — and handles each accordingly.

Show a report of open ClickHouse PRs whose only non-green CI check is "CH Inc sync" (or that are fully green) — i.e. effectively ready to merge. Groups by your authored PRs, PRs assigned to you (authored by others), and PRs by tracked authors (default groeneai). Shows the CH Inc sync state and whether each PR was ever approved; excludes already-merged PRs. Use when asked for "good PRs", merge-ready PRs, or PRs blocked only on the sync job.

Investigate a ClickHouse CI failure end-to-end from a PR or S3 report URL. Fetches the failed tests and their output, classifies each as flaky vs a real regression using play.clickhouse.com master history, and for every failure searches for both an existing tracking GitHub issue and an existing fix (open/merged PR) — reporting, per failure, whether an issue still needs to be created and whether a fix exists with its status (WIP, merged, already in this branch or not). Downloads and reads the harness artifacts only for failures that history does not explain, and reports a root-cause hypothesis. Read-only first pass — never commits, pushes, or edits.

Analyze ClickHouse Keeper stress-test results from play.clickhouse.com / keeper_stress_tests data warehouse. Use whenever the user asks about Keeper performance, validates Keeper PRs against stress dashboards, investigates regressions or improvements in Keeper nightlies, asks about specific date windows / SHAs / PR-sets in Keeper stress tests, wants per-PR or window-vs-window comparisons, asks "did this PR break Keeper", asks "what changed in Keeper between dates", or wants a summary report of Keeper stress runs. Triggers on terms like "keeper stress", "keeper PR", "keeper p99", "keeper memory", "keeper rps", "keeper nightly", "keeper-stress-tests", "keeper validation", "keeper regression", or any question referencing the keeper-stress Grafana dashboard. ALWAYS prefer this skill over re-deriving the workflow from scratch — it captures hard-learned lessons about cgroup-vs-Keeper memory, bench-harness confounds, noise floors, and per-PR attribution limits.

Check whether ClickHouse's supported versions (last 3 majors + latest LTS) have recent stable patch releases, diagnose why the scheduled AutoReleases pipeline failed, and identify which releases must be created manually. Use when asked "are the patch releases up to date", "why did autorelease fail", "which releases are missing", "did a release get skipped", during the bi-weekly release-health check, or when investigating create_release.yml / auto_releases.yml failures. Reproduces the full investigation: supported versions from SECURITY.md, per-version staleness, classification of the last N days of AutoReleases/CreateRelease failures (version-bump-PR guard vs missing release-maker runner vs other), the Slack cross-check that reveals the blocking PR, and gated remediation (close a stale robot bump PR, dispatch CreateRelease for a missing version).

Evaluate ClickHouse performance test results from existing CI/dashboard data or local perf.py runs. Use to check PR performance changes, run local performance tests, compare with history, assess flakiness, inspect coverage/PR relevance, and summarize whether a result is actionable.

Analyze CI performance comparison reports for a ClickHouse PR. Lists all regressions and improvements, cross-references with master history to distinguish real changes from flaky tests.

Update a ClickHouse third-party library (contrib submodule) to a new version. Handles fork management, submodule pointer bumps, CMake adaptation, and source code fixes. Use when the user wants to bump a dependency.

Review a numbered GitHub pull request for correctness, API safety, Go idioms, and protocol coverage, then post inline comments plus one updating summary. Use only when the user asks to review an open PR by number. For a local or pre-PR diff, do not use this skill — apply review-core.md in this directory instead.

Review changes in clickhouse-java for correctness, compatibility, API stability, and missing tests. Use when reviewing pull requests, commits, diffs, patches, or when the user asks for a code review.

| Analyzes a single GitHub issue at a time. Reads the description, defines labels and priority, researches additional information, and provides a short but detailed report. Use when the user asks to triage an issue, analyze a bug report, or categorize a GitHub issue.

Update ALLOWED_KEYWORD_ALIASES in ClickHouseSqlUtils.java and ENGINE_TO_TABLE_TYPE in DatabaseMetaDataImpl.java from failing test output. Use when StatementSQLTest.testAllowedKeywordAliasesMatchSystemKeywords or DatabaseMetaDataTest.testAllTableEnginesFromSystemTableEnginesAreMapped fails.

>- 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. "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.

>- Use when the user wants to run SQL — especially analytical SQL — on local files (parquet/csv/json), URLs, S3 paths, or remote databases (Postgres, MySQL, MongoDB, ClickHouse Cloud, Iceberg, Delta Lake) without setting up a server. Provides chDB — embedded ClickHouse SQL in Python with 1000+ functions, Session for stateful multi-step pipelines, parametrized queries, and cross-source joins via `s3()`, `mysql()`, `postgresql()`, `iceberg()`, `deltaLake()`, `remoteSecure()` table functions. analytical sources; uses ClickHouse SQL features (window functions, windowFunnel, geoToH3, JSON path ops, Session, parametrized queries); imports `chdb` or calls `chdb.query()`. SKIP this skill for pandas-style DataFrame method-chaining (use chdb-datastore instead) or ClickHouse server administration.

MUST USE when designing ClickHouse architectures, selecting between ingestion or modeling patterns, or translating best practices into workload-specific system designs. Complements clickhouse-best-practices with decision frameworks and explicit provenance labels.

MUST USE when investigating performance issues on a ClickHouse-managed Postgres instance. Provides an evidence-based RCA workflow that scrapes the Prometheus endpoint for system signal, pulls per-digest evidence from the Slow Query Patterns API, and recommends (does not apply) a fix.

Sets up and manages ClickHouse using the clickhousectl CLI — installs and runs a local ClickHouse server for development, and creates managed ClickHouse Cloud services for production (authentication, service creation, schema migration, application connection). Use when the user wants to build an application with ClickHouse, set up a local ClickHouse dev environment, create tables and start querying, deploy ClickHouse to production or ClickHouse Cloud, or migrate from a local setup to the cloud.

Sets up and manages Postgres using the clickhousectl CLI — runs a local Docker-backed Postgres for development, and creates and operates managed ClickHouse Cloud Postgres services (connections, TLS, runtime config, read replicas, failover, point-in-time restore). Use when the user wants a Postgres or PostgreSQL database for their application, a local Postgres dev environment, psql access, or a managed/production Postgres in ClickHouse Cloud, or mentions moving a local Postgres to production.

> Write idiomatic application code with the ClickHouse Node.js client (`@clickhouse/client`). Use this skill whenever a user is *building* against the Node.js client — configuring the client, pinging, inserting rows in JSON or raw formats, selecting and parsing results, binding query parameters, managing sessions and temporary tables, working with data types or customizing JSON parsing. Do NOT use for browser/Web client code.

> Generate TypeScript/JavaScript code that reads/decodes AND writes/encodes ClickHouse RowBinary streams for the ClickHouse HTTP server. Use this skill whenever a user wants to parse or produce `RowBinary`, `RowBinaryWithNames`, or `RowBinaryWithNamesAndTypes`. Node.js only, doesn't cover browsers.

> Troubleshoot and resolve common issues with the ClickHouse Node.js client (@clickhouse/client). Use this skill whenever a user reports errors, unexpected behavior, or configuration questions involving the Node.js client specifically — including socket hang-up errors, Keep-Alive problems, stream handling issues, data type mismatches, read-only user restrictions, proxy/TLS setup problems, or long-running query timeouts. Trigger even when the user hasn't precisely named the issue; vague symptoms like "my inserts keep failing" or "connection drops randomly" in a Node.js context are strong signals to use this skill. Do NOT use for browser/Web client issues.

> Fix CI failures and address code-review comments on a pull request that targets the protected `release` branch of `ClickHouse/clickhouse-js`. Release PRs are snapshots of `main` (their head branch is usually `main` itself) and cannot be edited directly — branch protection blocks pushing fixes onto them. Use this skill whenever the work is "fix the CI / address the review comments separate PR to `main`, then closes the loop on the original release PR by replying to and resolving the review threads. Triggers on phrasing like "fix this release PR", "the release PR is failing CI", "address the review comments but it's a release branch", or after checking out a PR whose base is `release`. Do NOT use this for ordinary feature/fix PRs that target `main` — for those, just push to the PR's own branch.

> version, sync the protected `release` branch from `main`, watch the npm publish (which is gated by a manual approval on the `npm-publish` environment), and create the GitHub Release from the CHANGELOG. Use this skill whenever the task is to "release", "cut a release", "publish a new version", or "ship" one (Web), `@clickhouse/client-common` (deprecated, rarely released), the standalone `@clickhouse/datatype-parser` (the type parser, under `packages/datatype-parser`), or `@clickhouse/rowbinary` (the RowBinary codec skill/package, under `skills/clickhouse-js-node-rowbinary`). The agent drives the GitHub Actions workflows (`gh workflow run`), watches CI, pauses at the human-judgment points (PR review, the approval gate, GitHub Release text), and hands the deployment-approval link back to the human. Do NOT use this for fixing a failing release PR — that is the `fix-release-pr` skill.

> Set up the `clickhouse-js` repository in a fresh checkout so the agent can run tests, lints, type checks, builds, or examples. Use this skill before invoking `npm run run-examples` script — or after pulling changes that touch any `package.json` (root, `examples/node`, or `examples/web`). Covers Node.js version requirements, installing dependencies across the npm workspaces and the two independent example packages, building the workspace packages so inter-package imports resolve, and starting ClickHouse via Docker Compose for integration tests. Do NOT use this skill for downstream user projects that merely depend on `@clickhouse/client` or `@clickhouse/client-web`; it is specific to contributing to the `ClickHouse/clickhouse-js` repo itself.

> Use the TypeScript language server (`typescript-language-server`) for precise references, hover (type signatures and JSDoc, including `@deprecated` info), workspace-wide symbol search, completions, and per-file type diagnostics. Prefer this over grep when you need to resolve a symbol's actual definition, find all usages of an exported API, or inspect inferred types across the `packages/*` workspaces. The server is preinstalled as a root devDependency — run the repository `setup` skill (`npm install`) first so `node_modules` is populated. Do NOT use this skill for downstream projects that merely depend on `@clickhouse/client`; it is specific to working inside this repo.

Fetch and report CI results for a silk PR. Use when the user asks to investigate, address, or fix CI failures, or refers to a PR without specifying what's broken.

> Convert ClickHouse blog content into docs pages. Use when porting a feature announcement, tutorial, or deep-dive from the blog into the docs site. Covers content extraction, asset handling, structural transformation, and voice conversion.

> Voice, style, and content rules for writing ClickHouse docs. Use when drafting new pages, rewriting sections, or applying editorial polish. Covers identity, voice, pacing, sentence habits, anti-patterns, AI-ism removal, prose tightening, editorial instinct, linking, keywords, content integrity, and marketing site alignment.

> Review a ClickHouse docs page before shipping. Runs the self-review checklist, Vale linting, and PR review rubric. Use when doing a final check, running Vale, or when asked "is this ready to ship."

> Review a docs PR from someone else. Triage issues by severity, draft comments with rationale, and focus on what matters. Use when reviewing a PR, not when checking your own work (use docs-pre-ship-review for that).

Migrate a click-ui component from styled-components to CSS Modules with byte-for-byte visual regression coverage. Use whenever a component still uses styled-components and is on the CSS Modules migration list.

Check C++ naming conventions against Google Style Guide. Use when checking if names follow conventions or when renaming identifiers.

Review C++ code against Google C++ Style Guide. Use when reviewing C++ code, pull requests, or when asked to check code style compliance.

Create and push a new semver release tag. Asks for release type (patch/minor/major), validates commit exists on remote, bumps version, and pushes the tag.

Google C++ Style Guide rules for writing clean, maintainable C++ code. Use when writing C++, reviewing code, discussing naming conventions, formatting, class design, or any C++ best practices. Covers headers, scoping, classes, functions, naming, comments, and formatting.

Share a Claude Code session to pastila.nl and return a viewer link. Shares the current session by default, or a session specified as a transcript path, a session id, or a project. Use when the user asks to share, publish, or get a link to this conversation or to a session/transcript.

Review a pull request, branch, or diff for the ClickHouse Entity Framework Core provider. Use when the user asks to review a PR, branch, commit range, or working tree diff for correctness, safety, performance, tests, documentation, and project compliance.

MUST USE when reviewing ClickHouse schemas, queries, or configurations. Contains 31 rules that MUST be checked before providing recommendations. Always read relevant rule files and cite specific rules in responses.

Guides users through setting up the ClickHouse MCP server connection bundled with this plugin. Use when the user first installs the plugin or has trouble connecting to ClickHouse.

Debug ClickHouse reference test failures (the tests/clickhouse-reference-{ast,format,explain,round-trip} suites). Use when one or more of those reference cases fail and you need to see what this library produced vs. the committed expected output. Maps a failing case to the right diff:* npm script and walks through isolating, diffing, and fixing the cause in the grammar/formatter/explain code.

Use when a user wants to wire an OpenTelemetry collector into a Managed ClickStack service on ClickHouse Cloud, either by deploying a new local collector (Docker run or Docker Compose) or by configuring their own existing collector, then send rich synthetic telemetry and verify it is visible in ClickStack.

Review a Pull Request for correctness, safety, performance, and compliance. Use when the user wants to review a PR or diff.