ClickHouse

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.

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

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.

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.

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.

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

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.

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.

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.

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.

Use when a user wants to build an application with ClickHouse, set up a local ClickHouse development environment, install ClickHouse, create a local server, create tables, or start developing with ClickHouse. Covers the full flow from zero to a working local ClickHouse setup.

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.

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. TRIGGER when: user wants SQL on parquet/csv/files or across remote 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 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.

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

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

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.

Generate C++ header files following Google Style Guide. Use when creating new header files or asking for a header template.

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.

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.

Drive a package release of `ClickHouse/clickhouse-js` end to end: bump the 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 of the packages: `@clickhouse/client` (Node.js), `@clickhouse/client-web` (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-r

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 any `npm run test:*`, `npm run lint`, `npm run typecheck`, `npm run build`, or `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.

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 on PR #N" and that PR's base branch is `release`: it routes the fix through a 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.

Use the TypeScript language server (`typescript-language-server`) for precise code intelligence in the `clickhouse-js` repository: go-to-definition, find 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.

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.

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.

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.

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.

Use when migrating ClickHouse docs pages from Docusaurus (clickhouse-docs) to Mintlify format in this repo, or when wiring up the migration script. Covers frontmatter rewrites, body transforms, component mapping, link normalization, and redirect generation. Slugs are canonical and must never be rewritten.

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.

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.

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.

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

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.