1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | clickhouse-best-practices-clickhouse-agent-skills |
| 项目自述名称 | ClickHouse Agent Skills（仓库自述名，本子技能自身标题为 “ClickHouse Best Practices”） |
| 作者/维护者 | ClickHouse Inc（官方账号） |
| 来源链接 | https://github.com/ClickHouse/agent-skills/tree/main/skills/clickhouse-best-practices |
| 许可证 | Apache-2.0（GitHub API） |
| GitHub Stars | 490（GitHub API；为 agent-skills 整仓库星数，仓库共含 11 个子技能，本技能是 README 首位列出的旗舰技能） |
| Forks | 31（GitHub API） |
| 最新版本 | 0.4.0（技能自身 metadata.json） |
| 安装方式 | npx skills add clickhouse/agent-skills 或官方 CLI clickhousectl skills（README） |
2. 功能介绍与亮点
把 ClickHouse 工程师踩过的坑编码成 31 条规则，覆盖 schema 设计、查询优化、数据插入、agent 连接安全四大类，按 CRITICAL/HIGH/MEDIUM 分级排序。
- 每条规则都配“错误写法 vs 正确写法”的 SQL 对照示例，而非笼统建议
- 专设“agent 查询安全”规则：强制 LIMIT、扫描行数上限、超时设置，防止 agent 对大表跑出无界查询拖垮集群
- 明确的 agent 工作流：连接 → 发现 schema → 规划 → 执行 → 出错后收窄重试
- 官方持续维护，报告发布前 3 天仍有提交
3. 适用场景
固定分类：数据分析与可视化
用 Claude Code 等 agent 设计 ClickHouse 表结构、优化慢查询、规划数据摄入策略的开发者与数据工程师；尤其适合熟悉传统 SQL 但不了解 ClickHouse 列式存储、稀疏索引、MergeTree 机制的用户——这类背景差异正是 agent 凭通用数据库直觉给出误导性建议的高发区。
4. 跨 Agent 兼容性
- Claude Code：原生支持——仓库自带
.claude-plugin市场清单，README 将其列为首个支持对象，官方安装命令可自动检测安装 - Codex：未验证——仓库未见
.codex-plugin清单（对比同类官方仓库如 MongoDB/Redis 均带有该清单），技能本身遵循 agentskills.io 开放规范，理论上可手动放入技能目录，但未见官方声明或亲自验证 - OpenClaw：未验证——抓取材料中未出现相关声明
- Hermes Agent：未验证——抓取材料中未出现相关声明
5. 推荐理由
ClickHouse 官方把工程师内部踩过的坑直接编码成可引用、可审计的规则集，而不是一份笼统的最佳实践博客——agent 审查 schema 或查询时会逐条引用规则号并给出“当前写法/应改写法/修复方式”，这种结构化输出比让 agent 凭通用 SQL 直觉临场发挥可靠得多，对刚接触列式数据库的用户帮助尤其明显。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 8 | 子目录本身无独立 star 计数，合集仓库整体 490+ star 不可作为本子技能依据；经 GitHub code search 交叉验证，本技能已被 31k+ star 的开源项目 langfuse 直接引入（vendored）进自己的 agent skills 目录，并被 VoltAgent/awesome-agent-skills、xu-xiang/awesome-top-skills 等多个第三方 skills 精选列表收录，存在可验证的下游采用证据（GitHub code search 命中约 450 处引用，数字为近似估计） |
| 可用性 | 9 | npx skills add clickhouse/agent-skills 或官方 CLI clickhousectl skills 一条命令安装，Claude Code 另带 .claude-plugin 市场清单可自动检测安装；31 条规则逐条配错误/正确 SQL 对照示例并按 CRITICAL/HIGH/MEDIUM 分级；报告发布前 3 天仓库仍有提交，开源自建即可完整使用、无需付费账号 |
| 安全性 | 9 | 见下方安全检查清单 |
| 综合 | 8.7 | 三项均值 |
安全检查清单：
| 检查项 | 结果 |
|---|---|
| ① Shell 命令执行 | 技能本身为纯规则文档，不含可执行脚本；实际查询经用户自行连接的 MCP 执行，非技能内置行为 |
| ② 联网外发 | 无默认外联；仅当用户主动通过 MCP 连接自己的 ClickHouse 实例时才产生网络行为 |
| ③ API key/凭据 | 基础“最佳实践审查”无需任何凭据；仅可选的实时查询功能需要用户自己的 MCP Server 凭据，技能本身不存储 |
| ④ 可疑指令 | 抓取的 README、SKILL.md、多条规则文件中未发现要求执行特权操作或数据外发的可疑指令 |
| ⑤ 作者信誉 | ClickHouse Inc 官方 GitHub 组织账号 |
| ⑥ License | Apache-2.0，明确 |
| ⑦ 维护时间 | 报告发布前 3 天有最近提交，活跃维护 |
7. 跟同类 Skills 相比的优势
同为“数据库厂商官方 agent 技能”的其他项目与本技能的定位差异：
| 技能 | 厂商 | 规则/覆盖范围 | 是否需付费账号 | 独有特点 |
|---|---|---|---|---|
| ClickHouse Best Practices（本次推荐） | ClickHouse Inc | 31 条规则，schema/查询/插入/agent 安全 | 否，开源自建即可用 | 每条规则含 SQL 对照示例+影响分级；内置 agent 查询安全护栏 |
| MongoDB Schema Design | MongoDB | Schema 设计模式与反模式 | 否 | 侧重文档模型的嵌入 vs 引用决策 |
| Elasticsearch ES|QL | Elastic | 属 25+ 子技能大合集的一支 | 需 Elasticsearch/Elastic Cloud 实例 | 覆盖面广但单技能notoriety被稀释 |
| Redis Core | Redis | 连接、集群、安全等 8 个子技能 | 否 | 官方博客单独宣传“让 AI 写 Redis 代码” |
ClickHouse 的差异化在于：唯一把安全护栏（查询超时/扫描上限）写进规则本身的厂商技能，且不依赖付费云账号即可完整使用。
8. 用户评价
该技能已被 Hacker News 讨论帖与 The New Stack 的科技媒体报道提及，但两处正文均无法取得可引用内容（HN 页面持续返回 429 限流；The New Stack 页面仅渲染出订阅框、未含正文），因此目前尚无可具名引用的独立用户评价。
9. 其他补充
仓库遵循 agentskills.io 开放技能规范，欢迎社区通过 PR 贡献新规则；同仓库还含 chdb（Python 内嵌分析）、clickhousectl 部署等其他 10 个技能，均可按需单独安装。
10. 安装使用方式
- 推荐方式：
npx skills add clickhouse/agent-skills，CLI 会自动检测已安装的 agent 并询问装到哪个目录 - ClickHouse 官方 CLI：
clickhousectl skills - 安装后无需重启；agent 在处理
CREATE TABLE、ALTER TABLE、JOIN 优化、慢查询排查等场景时会按 SKILL.md 描述自动触发 - 如需 agent 直接连接数据库执行查询（而非仅做静态审查），需额外配置 ClickHouse MCP Server 并按
rules/agent-connect-mcp.md指引提供连接凭据
11. 注意事项
- 技能面向 ClickHouse 24.1+ 版本设计，过旧版本可能不完全适用
- 本技能是合集仓库
ClickHouse/agent-skills中的一个子目录，仓库同时含 chdb、clickhousectl 等其他 10 个技能，只需 SQL 最佳实践时只装本子目录即可 - Codex / OpenClaw / Hermes Agent 的兼容性未获官方明确声明，跨 agent 使用前建议自行验证 SKILL.md 能否被目标 agent 正确加载
- 让 agent 直接连接真实数据库执行查询需要额外配置 MCP 与凭据，基础“最佳实践审查”功能不需要