clickhouse-js-node-coding-clickhouse-agent-skills

1. 基本信息

项目	内容
名称	clickhouse-js-node-coding-clickhouse-agent-skills
项目自述名称	仓库自述名 “ClickHouse Agent Skills”（本子技能自身标题为 “ClickHouse Node.js Client — Coding”，在仓库 README 的“Available Skills”清单中独立列出）
作者/维护者	ClickHouse Inc（官方仓库）；子技能全部提交均来自 ClickHouse 员工 Peter Leonov（GitHub 账号 company 字段实测为 “ClickHouse”）
来源链接	https://github.com/ClickHouse/agent-skills/tree/main/skills/clickhouse-js-node-coding
许可证	Apache-2.0（GitHub API 实测）
GitHub Stars	该子目录本身无独立 star 计数；合集仓库 agent-skills 整体 496 star / 32 forks（GitHub API 实测），该数字属整个合集仓库，不代表本子技能自身热度
最新版本	仓库未打版本标签；子技能 2026-05-21 创建，2026-06-30 随一次跨技能同步更新过；所封装的官方 Node.js 客户端包 `@clickhouse/client` 当前 npm 最新版本 1.23.1（npm 官方 registry 实测）
安装方式	`npx skills add clickhouse/agent-skills` 或官方 CLI `clickhousectl skills`；无需额外依赖安装

2. 功能介绍与亮点

ClickHouse Node.js Client — Coding 是官方 Node.js 客户端 @clickhouse/client 的编码参考手册，专注“如何正确写”而非报错排查，以任务索引表 + 12 个独立参考文档的结构组织：

任务索引表覆盖客户端配置、压缩、健康检查、插入格式选择、跨库/跨表插入、值与日期精度插入、异步插入、查询结果解析、参数化查询、会话与临时表、新数据类型（Dynamic/Variant/JSON/Time/QBit）、自定义 JSON 序列化共 12 类场景，每类各配一份 3–11KB 的独立参考文档（实测全部真实存在，非空链接）
逐项标注方法适用版本号（如 BigInt 参数需客户端 ≥1.15.0、QBit 类型需服务端 ≥25.10），避免给出对用户当前版本无效的代码建议
明确要求在回答参数绑定问题时必须显式提示“SQL 注入风险”字样，把安全意识内嵌进日常编码指导，而非只在专门的安全文档里提
与同仓库的 clickhouse-js-node-troubleshooting（面向“报错后怎么修”）分工明确、互不重叠，专注“从零开始怎么写对”
仓库统一通过 npx skills add/clickhousectl skills 分发，README 明确写明面向 Claude Code、Cursor、Copilot 等多种编码 Agent

3. 适用场景

固定分类：工程效率与代码质量

适合使用 ClickHouse 官方 Node.js 客户端从零构建应用的后端/全栈开发者：搭建 API 服务的插入/查询逻辑、处理会话与临时表、正确使用参数化查询防注入、适配新版本数据类型等场景，尤其适合刚接入该客户端、想按官方推荐范式而非试错摸索来写代码的中初级用户。

4. 跨 Agent 兼容性

Claude Code：✅ 原生支持——仓库自带 .claude-plugin 市场清单，npx skills add 可自动检测并安装
Codex：✅ 支持——npx skills add 所用安装器（npm 包 skills，实测其 repository 字段指向 vercel-labs/skills）源码 src/agents.ts 中显式定义了 codex agent profile（探测 $CODEX_HOME 或 /etc/codex）
OpenClaw：✅ 支持——同一安装器源码中定义了 openclaw profile（探测 ~/.openclaw 等目录）
Hermes Agent：✅ 支持——同一安装器源码中定义了 hermes-agent profile（探测 ~/.hermes 或 $HERMES_HOME）

以上四项结论均直接读取该技能实际使用的安装器源码得出，非仓库自身声明。

5. 推荐理由

官方ClickHouse团队出品，按场景拆分的12份编码参考文档配精确版本号对照，帮开发者从第一行代码起就写对Node客户端用法。

6. 评分

维度	分数	说明
受欢迎程度	6	子目录自身提交记录较少（2 次，均来自同一员工），无独立 issue/PR 讨论；但所属合集仓库由 ClickHouse 官方团队多名成员（含 Anthropic 员工协作过 Claude Code 插件结构）持续共同维护，具备真实团队背书
可用性	8	单条 `npx skills add` 命令即装；12 类场景各配独立参考文档（实测全部真实存在），含版本号对照表；子目录最近一次更新约一个月前，仓库整体 10 天前仍有提交；无付费依赖、无需注册账号
安全性	9	见下方安全检查清单
综合	7.7	三项均值

安全检查清单：

检查项	结果
① Shell 命令执行范围	本技能是纯编码指导文档，不涉及执行任意 shell 命令
② 运行时联网外发数据	指导生成的代码连接用户自己配置的 ClickHouse 服务地址，不涉及向第三方地址外发数据
③ API key/凭据	不涉及新增凭据，沿用用户已有的 ClickHouse 连接信息
④ 可疑指令	审阅 SKILL.md 全文与全部 12 个参考文档，未发现 prompt injection 或异常指令；反而主动要求在参数绑定场景显式提示 SQL 注入风险
⑤ 作者/组织信誉	ClickHouse Inc 官方组织账号，提交者身份可核实为该公司员工
⑥ License	Apache-2.0，明确
⑦ 最近维护时间	子目录最近一次内容更新约一个月前，仓库整体近日仍有提交，维护活跃

7. 跟同类 Skills 相比的优势

同为“官方数据库厂商 Node.js 客户端编码指导”类目的技能与本技能的定位差异：

技能	出品方	覆盖范围	深度
ClickHouse Node.js Client — Coding（本次推荐）	ClickHouse Inc	仅 `@clickhouse/client`（Node.js 运行时）	12 类编码场景各有独立参考文档，含方法签名建议与客户端/服务端版本号对照
mongodb-connection（mongodb/agent-skills）	MongoDB Inc	泛化覆盖 Node.js、Python、Java、Go、C#、Ruby、PHP 等全部官方驱动语言	单一文档讲解连接池配置原理与容量估算公式，不覆盖插入/查询/数据类型等具体编码任务

MongoDB 的方案胜在跨语言通用性，聚焦连接池这一个横切关注点；本技能牺牲了跨语言覆盖面与连接池调优深度，换来针对 Node.js 单一运行时从配置到插入、查询、参数化、新数据类型的全流程编码覆盖，更适合已经确定技术栈、需要系统学习该客户端全套 API 用法的场景。

8. 用户评价

该技能目前在第三方平台尚无具名用户评价；其所属仓库 ClickHouse/agent-skills 迄今仅有 2 个非 PR 性质的讨论 issue，暂无用户就本技能本身发起过公开讨论。

9. 其他补充

仓库遵循 agentskills.io 开放技能规范；同仓库还含 clickhouse-best-practices、clickhouse-architecture-advisor、clickhouse-js-node-troubleshooting、chdb-sql、chdb-datastore、clickhousectl-local-dev 等其他技能，均可按需单独安装。

10. 安装使用方式

推荐方式：npx skills add clickhouse/agent-skills，CLI 会自动检测已安装的 agent 并询问装到哪个目录，仅需勾选本技能即可，无需装整仓库
ClickHouse 官方 CLI：clickhousectl skills
安装后无需重启；当在 Node.js 环境中使用 @clickhouse/client 编写插入、查询、参数绑定、会话管理等代码时会自动触发

11. 注意事项

仅覆盖 Node.js 运行时的 @clickhouse/client 包，明确不适用于浏览器端/Next.js Edge 运行时/Cloudflare Workers 场景下的 @clickhouse/client-web
与同仓库 clickhouse-js-node-troubleshooting 技能是编码/排查两个互补分工，若已写好代码却遇到报错，应改装后者
不覆盖流式传输、Parquet 文件流、TLS/RBAC 权限、CREATE TABLE 建表模式等主题，这些在客户端官方仓库 ClickHouse/clickhouse-js 的示例目录中另有说明
本技能是合集仓库 ClickHouse/agent-skills 中的一个子目录，只需该功能时装本子目录即可