ClickHouse 发布 Agent Skills：28 条规则让 AI 助手学会 ClickHouse
ClickHouse 发布了官方 Agent Skills，一套开源的最佳实践规则集，基于 Anthropic 的 Agent Skills 规范打包了 28 条经工程师和社区验证的 ClickHouse 实操规则，涵盖 Schema 设计、查询优化和数据摄入。执行 npx skills add clickhouse/agent-skills 即可添加到本地环境，AI 助手（如 Claude Code）会自动在需要时调用这些规则，避免常见错误（如错误的 ORDER BY、不可扩展的 JOIN、遗漏物化视图）。仓库使用 Apache 2.0 许可，欢迎社区贡献经验。
We’re releasing the official ClickHouse Agent Skills: a set of open-source, packaged skills encoded with ClickHouse best practices learned by our engineers and community. These skills provide your AI assistant with 28 prioritized rules for schema design, query optimization, and data ingestion. It helps your agent go from a general-purpose LLM to a ClickHouse power user.
我们正式发布 ClickHouse Agent Skills：一套开源、打包的技能，融入了我们的工程师和社区总结的 ClickHouse 最佳实践。这些技能为 AI 助手提供 28 条按优先级排序的规则，涵盖 schema 设计、查询优化和数据摄入，帮助智能体从通用大语言模型进化为 ClickHouse 行家。
The repo is open and Apache licensed for everyone to contribute to, so if you've got some hard-won lessons about how to best use ClickHouse, we'd love for you to share.
You can add these skills to your local environment in seconds:
npx skills add clickhouse/agent-skills
The CLI will detect which agentic interfaces you have installed and drop the instructions in the right place. Agents that support skills should start to use them automatically when appropriate, but you can also manually invoke them (for example, in Claude Code, you can use /clickhouse-best-practices).
仓库以 Apache 协议开源，欢迎所有人贡献。如果你有来之不易的 ClickHouse 使用心得，我们非常乐意你分享。
只需几秒，就能将这些技能添加到本地环境：
npx skills add clickhouse/agent-skills
CLI 会检测你安装了哪些智能体界面，并将指令放到正确位置。支持技能的智能体在适当场景下会自动调用，你也可以手动触发（例如在 Claude Code 中使用 /clickhouse-best-practices）。
LLMs are a great accelerator, and we believe that they are only going to become more common in developer workflows as we build towards agentic analytics. But, they don't (yet?) always get specialised systems like ClickHouse exactly right. We’ve seen some developers hit walls when LLMs make functional, but less-than-perfect, choices:
- Choosing the wrong ORDER BY or data types.
- Writing JOINs that don't scale or failing to batch inserts.
- Missing out on Materialized Views or specialized indexes.
These choices can lead to friction later down the line when you reach production, or need to scale. We want to support developers using AI, and while our docs contain a wealth of information on how to do these things correctly, LLMs don’t always find the right information at the right time.
LLM 是出色的加速器，我们相信随着向智能分析演进，它们会越来越融入开发流程。但它们（目前？）未必总能精准把握 ClickHouse 这样专精的系统。我们见过不少开发者碰壁，就是因为 LLM 做出的选择能用但不理想：
- 选错 ORDER BY 或数据类型；
- JOIN 写法不可扩展，或没做批量插入；
- 忽略物化视图或专用索引。
这些选择在后期推向生产或需要扩展时会带来麻烦。我们想支持使用 AI 的开发者——虽然文档里有大量正确做法，但 LLM 并非总能在合适的时候找到合适的信息。
We’ve built these skills using the Agent Skills specification recently released by Anthropic. It’s a lightweight, agent-agnostic format that allows us to encode deep domain knowledge into a format that LLMs can invoke when they actually need it.
这些技能基于 Anthropic 最近发布的 Agent Skills 规范构建。这是一种轻量、与智能体无关的格式，让我们能将深厚的领域知识编码成 LLM 能在真正需要时调用的形式。
The initial release focuses on the high-impact best practices that are relevant to almost all ClickHouse users:
- Schema design
- Primary Key selection
- Data Types
- Query performance
- JOIN optimization
- Mutation avoidance
- Data ingestion
- Insert batching
- Async inserts
- Advanced tools
- Materialized Views
- Partitioning strategies
This is just the start. We’re going to keep expanding this with deeper knowledge on cluster configurations, engine-specific optimizations, complex data pipeline patterns, and more.
Check out the repo and join us in Slack to let us know what rules we should add next.
首发版本聚焦于几乎对所有 ClickHouse 用户都关键的高影响最佳实践：
- Schema 设计
- 主键选择
- 数据类型
- 查询性能
- JOIN 优化
- 避免 Mutation
- 数据摄入
- 插入批量化
- 异步插入
- 高级工具
- 物化视图
- 分区策略
这仅仅是一个开始。我们将持续扩展，纳入集群配置、引擎特定优化、复杂数据管道模式等更深层的知识。
欢迎查看仓库，加入 Slack 告诉我们下一步应该添加哪些规则。