clickhouse-best-practices
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.
Security Assessment
Detected risks:
About clickhouse-best-practices
The `clickhouse-best-practices` skill provides structured guidance for reviewing and optimizing ClickHouse database schemas, queries, and configurations. It addresses the challenges developers and data engineers face when working with ClickHouse’s unique architecture, including columnar storage, sparse indexes, and MergeTree mechanics, which can make conventional database intuition misleading. By codifying 31 essential rules, the skill ensures that any recommendations or assessments are consistent, validated, and aligned with ClickHouse-specific behaviors. It enforces a disciplined approach that minimizes performance pitfalls, data inconsistencies, and inefficient query patterns.
This skill offers several key capabilities. It organizes best practices into four main categories: schema design, query optimization, data insertion, and agent connectivity. Users are guided through step-by-step procedures for schema reviews, query analysis, and safe agent query execution, with rules prioritized by impact. The skill also specifies procedural workflows for AI agents connecting to ClickHouse, including connection setup, schema discovery, query planning, execution, and error recovery. Every recommendation is grounded in either a specific rule, general ClickHouse guidance, or verified documentation, ensuring traceable and authoritative advice. The rules cover areas such as primary key planning, column ordering, data type selection, partitioning, join algorithm choice, pre-join filtering, and secondary index usage.
This skill is ideal for database administrators, data engineers, and AI agents that interact with ClickHouse clusters. It is particularly useful in environments where performance, correctness, and maintainability are critical. Users can leverage it during schema design reviews, query optimization tasks, automated agent operations, or any scenario requiring systematic evaluation of ClickHouse systems. Its rule-based structure ensures consistent application of best practices across teams and projects, making it a reliable tool for both human and AI-assisted ClickHouse management.
FAQ
How do I apply the clickhouse-best-practices skill when reviewing schemas or queries?
Always check the relevant rules in the `rules/` directory first. Apply the rules to your schema, query, or configuration, and cite them in your response. If no rule applies, use general ClickHouse knowledge or documentation, and if needed, consult current web resources.
Is this skill compatible with all ClickHouse versions?
The skill is based on guidance provided by ClickHouse Inc and is intended for use with versions where MergeTree tables, sorting keys, and sparse indexes are supported. Users should verify that specific features referenced in rules are available in their ClickHouse version.
Can AI agents use this skill for automated query execution?
Yes. The skill includes procedural workflows for agent connectivity, schema discovery, query planning, execution, and error recovery, ensuring safe and efficient AI interactions with ClickHouse.
Are there limitations to the rules provided?
The skill contains 31 prioritized rules covering schema, query, insert, and agent operations. While comprehensive, it may not cover every edge case. When uncertain, users should supplement with general ClickHouse guidance or up-to-date documentation.
Do I need to cite the rules when using this skill?
Yes. Any recommendation or assessment should reference the specific rule, general guidance, or documentation source to maintain traceability and authority.
All Files
37 filesInstall clickhouse-best-practices
Quick Setup:
- Copy the skill folder to
.claude/skills/ - Claude will automatically detect and use the skill
Repository
clickhouse/agent-skills