Skip to content

Add clickhouse-js-node-coding AI agent skill#702

Merged
peter-leonov-ch merged 33 commits into
mainfrom
copilot/draft-nodejs-coding-ai-skill
May 5, 2026
Merged

Add clickhouse-js-node-coding AI agent skill#702
peter-leonov-ch merged 33 commits into
mainfrom
copilot/draft-nodejs-coding-ai-skill

Conversation

Copilot AI commented May 5, 2026

Copy link
Copy Markdown
Contributor

Summary

Drafts a new AI-agent skill at skills/clickhouse-js-node-coding/, sourced from the examples/node/coding/*.ts corpus and scoped to day-to-day coding against @clickhouse/client (Node). Mirrors the structure of the existing clickhouse-js-node-troubleshooting skill so the two compose cleanly.

  • SKILL.md — frontmatter (name + trigger description), Node-only banner, How-To-Use rules (right method per task, version-constraint callouts, JSONEachRow default, never template-literal user input), Task Index mapping intent → reference file, and an "Out of scope" section that delegates only to the existing clickhouse-js-node-troubleshooting skill and routes the other topics (performance, security, schema-and-deployments, web) to the corresponding examples/node/{performance,security,schema-and-deployments}/ and examples/web/ directories instead of pointing at sibling skill names that don't exist in this repo.
  • reference/ (11 files) — one per Task Index row, each opening with a version-applies banner and citing the backing example(s):
    • client-configuration.md, ping.md, insert-formats.md, insert-columns.md, insert-values.md, async-insert.md, select-formats.md, query-parameters.md, sessions.md, data-types.md, custom-json.md.
  • evals/evals.json — 8 starter evals using the same { id, prompt, expected_output, files, expectations } shape as the troubleshooting skill, covering one prompt per major reference file (config, ping, insert, columns, parameter binding, sessions, JSON column type, custom JSON parser).

In response to review feedback, the "Configuration via URL parameters" section in reference/client-configuration.md was tightened to spell out the fixed allowlist (plus the clickhouse_setting_ / ch_ / http_header_ prefixes) and to call out the Unknown URL parameters: ... throw, with a citation to packages/client-common/src/config.ts. The equivalent config-object example in the same file was corrected to import ClickHouseLogLevel from @clickhouse/client and use log: { level: ClickHouseLogLevel.TRACE } instead of the invalid top-level log_level: 'TRACE', with a note clarifying the URL-parameter-to-config-object mapping for log levels. Additionally, reference/select-formats.md was updated so ResultSet.close() is documented as synchronous (no await) in both the methods table row and the "stream half-consumed" common-pitfall note, matching the actual close(): void API. Following further review, every remaining reference to the non-existent clickhouse-js-node-performance sibling skill was replaced with a link to the in-repo examples/node/performance/ directory across SKILL.md, reference/async-insert.md, reference/insert-formats.md, and reference/select-formats.md (intro, methods table, and Parquet-related notes), so the skill no longer points at unavailable skill identifiers. The "Session-level SET commands" snippet in reference/sessions.md was also made self-contained by adding the createClient and node:crypto imports, setting max_open_connections: 1 alongside session_id (consistent with the per-client concurrency guidance earlier in the same doc), and ending with await client.close().

No runtime code or build config is touched. The client-node prepack script already copies the repo-root skills/ directory into the published package, so the new skill ships to npm without further changes.

Checklist

  • A human-readable description of the changes was provided to include in CHANGELOG

Copilot AI self-assigned this May 5, 2026
Copilot AI review requested due to automatic review settings May 5, 2026 10:01
Copilot AI review requested due to automatic review settings May 5, 2026 10:01
@codecov

codecov Bot commented May 5, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

Comment thread skills/clickhouse-js-node-coding/evals/evals.json Outdated
Comment thread skills/clickhouse-js-node-coding/evals/evals.json Outdated
Copilot AI review requested due to automatic review settings May 5, 2026 17:30
@CLAassistant

Copy link
Copy Markdown

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ peter-leonov-ch
❌ Copilot
You have signed the CLA already but the status is still pending? Let us recheck it.

@peter-leonov-ch

Copy link
Copy Markdown
Collaborator

Eval results:

  ┌─────────────────────────┬────────────┬───────────────┐
  │          Eval           │ with_skill │ without_skill │
  ├─────────────────────────┼────────────┼───────────────┤
  │ 0 createclient-config   │ 3/3        │ 2/3           │
  ├─────────────────────────┼────────────┼───────────────┤
  │ 1 ping-health-check     │ 3/3        │ 1/3           │
  ├─────────────────────────┼────────────┼───────────────┤
  │ 2 insert-array-json     │ 3/3        │ 3/3           │
  ├─────────────────────────┼────────────┼───────────────┤
  │ 3 insert-subset-columns │ 3/3        │ 2/3           │
  ├─────────────────────────┼────────────┼───────────────┤
  │ 4 parameterize-queries  │ 3/3        │ 3/3           │
  ├─────────────────────────┼────────────┼───────────────┤
  │ 5 sessions-temp-tables  │ 3/3        │ 2/3           │
  ├─────────────────────────┼────────────┼───────────────┤
  │ 6 json-column-type      │ 3/3        │ 2/3           │
  ├─────────────────────────┼────────────┼───────────────┤
  │ 7 custom-json-parser    │ 2/4        │ 0/4           │
  └─────────────────────────┴────────────┴───────────────┘

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR introduces a new documentation-backed Copilot skill (clickhouse-js-node-coding) intended to guide day-to-day application coding against the Node.js ClickHouse client (@clickhouse/client), mirroring the structure of the existing troubleshooting skill.

Changes:

  • Added a new skill definition (SKILL.md) with intent routing (“Task Index”), usage rules, and scope boundaries for Node-only coding scenarios.
  • Added 11 reference markdown files under reference/ covering common coding tasks (configuration, ping, inserts/selects, query parameters, sessions, data types, custom JSON handling).
  • Added starter evals (evals/evals.json) to validate the skill’s expected behaviors across major topics.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 8 comments.

Show a summary per file
File Description
skills/clickhouse-js-node-coding/SKILL.md Skill frontmatter + usage rules + task index + out-of-scope routing
skills/clickhouse-js-node-coding/reference/client-configuration.md Client configuration guidance, including URL-based config examples
skills/clickhouse-js-node-coding/reference/ping.md client.ping() usage patterns and health-check mapping
skills/clickhouse-js-node-coding/reference/insert-formats.md Insert format chooser + JSON format shape guidance
skills/clickhouse-js-node-coding/reference/insert-columns.md columns option patterns + ephemeral columns + cross-db inserts
skills/clickhouse-js-node-coding/reference/insert-values.md INSERT ... SELECT and INSERT ... VALUES patterns, Date/Decimal guidance
skills/clickhouse-js-node-coding/reference/async-insert.md Async insert settings and expected behavior tradeoffs
skills/clickhouse-js-node-coding/reference/select-formats.md Select formats overview + ResultSet method guidance
skills/clickhouse-js-node-coding/reference/query-parameters.md ClickHouse {name: Type} parameter binding rules and pitfalls
skills/clickhouse-js-node-coding/reference/sessions.md session_id usage, temp tables, and session-scoped SET
skills/clickhouse-js-node-coding/reference/data-types.md Modern server-side types (Dynamic/Variant/JSON/Time/Time64) guidance
skills/clickhouse-js-node-coding/reference/custom-json.md Custom JSON parse/stringify configuration patterns
skills/clickhouse-js-node-coding/evals/evals.json Initial eval corpus for the new skill

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread skills/clickhouse-js-node-coding/reference/client-configuration.md Outdated
Comment thread skills/clickhouse-js-node-coding/SKILL.md Outdated
Comment thread skills/clickhouse-js-node-coding/reference/sessions.md
Comment thread skills/clickhouse-js-node-coding/reference/insert-values.md Outdated
Comment thread skills/clickhouse-js-node-coding/reference/insert-formats.md Outdated
Comment thread skills/clickhouse-js-node-coding/reference/select-formats.md Outdated
Comment thread skills/clickhouse-js-node-coding/reference/custom-json.md Outdated
Comment thread skills/clickhouse-js-node-coding/SKILL.md Outdated
Copilot AI review requested due to automatic review settings May 5, 2026 21:27
Copilot AI requested a review from peter-leonov-ch May 5, 2026 21:31

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 9 comments.


💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread skills/clickhouse-js-node-coding/evals/evals.json Outdated
Comment thread skills/clickhouse-js-node-coding/reference/client-configuration.md Outdated
Comment thread skills/clickhouse-js-node-coding/reference/client-configuration.md
Comment thread skills/clickhouse-js-node-coding/reference/select-formats.md Outdated
Comment thread skills/clickhouse-js-node-coding/reference/select-formats.md Outdated
Comment thread skills/clickhouse-js-node-coding/reference/select-formats.md
Comment thread skills/clickhouse-js-node-coding/reference/custom-json.md Outdated
Comment thread skills/clickhouse-js-node-coding/reference/insert-formats.md Outdated
Comment thread skills/clickhouse-js-node-coding/SKILL.md Outdated
Copilot AI review requested due to automatic review settings May 5, 2026 21:37

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 4 comments.


💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread skills/clickhouse-js-node-coding/evals/evals.json Outdated
Comment thread skills/clickhouse-js-node-coding/reference/select-formats.md Outdated
Comment thread skills/clickhouse-js-node-coding/reference/data-types.md Outdated
Comment thread skills/clickhouse-js-node-coding/SKILL.md Outdated
Copilot AI review requested due to automatic review settings May 5, 2026 21:45
Comment thread skills/clickhouse-js-node-coding/reference/client-configuration.md Outdated

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 5 comments.


💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread skills/clickhouse-js-node-coding/reference/client-configuration.md Outdated
Comment thread skills/clickhouse-js-node-coding/reference/insert-values.md Outdated
Comment thread skills/clickhouse-js-node-coding/reference/select-formats.md Outdated
Comment thread skills/clickhouse-js-node-coding/reference/data-types.md Outdated
Comment thread skills/clickhouse-js-node-coding/evals/evals.json Outdated
Copilot AI requested a review from peter-leonov-ch May 5, 2026 21:52
Copilot AI review requested due to automatic review settings May 5, 2026 21:59
Copilot AI and others added 19 commits May 6, 2026 01:40
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Agent-Logs-Url: https://github.com/ClickHouse/clickhouse-js/sessions/7a14296b-2586-40ad-93ce-7cf3167e0576

Co-authored-by: peter-leonov-ch <209667683+peter-leonov-ch@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
…performance/

Agent-Logs-Url: https://github.com/ClickHouse/clickhouse-js/sessions/e524ac60-3565-479f-a4cb-7f135d4665ad

Co-authored-by: peter-leonov-ch <209667683+peter-leonov-ch@users.noreply.github.com>
… and close()

Agent-Logs-Url: https://github.com/ClickHouse/clickhouse-js/sessions/6d318173-241e-47db-add0-da209ef2d77d

Co-authored-by: peter-leonov-ch <209667683+peter-leonov-ch@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
… with examples/node/performance/ links

Agent-Logs-Url: https://github.com/ClickHouse/clickhouse-js/sessions/487e604a-a243-4732-9611-4a1aff32ec19

Co-authored-by: peter-leonov-ch <209667683+peter-leonov-ch@users.noreply.github.com>
@peter-leonov-ch peter-leonov-ch force-pushed the copilot/draft-nodejs-coding-ai-skill branch from 452aca6 to 95c4a59 Compare May 5, 2026 23:40
@peter-leonov-ch peter-leonov-ch marked this pull request as ready for review May 5, 2026 23:40
@peter-leonov-ch peter-leonov-ch requested a review from mshustov as a code owner May 5, 2026 23:40

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 2 comments.


💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread skills/clickhouse-js-node-coding/reference/client-configuration.md Outdated
Comment thread skills/clickhouse-js-node-coding/reference/custom-json.md Outdated
peter-leonov-ch and others added 2 commits May 6, 2026 01:42
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
@peter-leonov-ch peter-leonov-ch merged commit 360dc24 into main May 5, 2026
61 checks passed
@peter-leonov-ch peter-leonov-ch deleted the copilot/draft-nodejs-coding-ai-skill branch May 5, 2026 23:46
peter-leonov-ch added a commit that referenced this pull request May 9, 2026
`AGENTS.md` had drifted from reality after PRs #662#712: it claimed
`examples/web` has no `performance/` folder, pointed at a placeholder
docs path, and said nothing about the `skills/` directory or the
`.claude/skills/setup/` skill that replaced `copilot-setup-steps.yml`.

## Summary

- **Examples › `performance/`** — drop the "no `performance/` folder
under `examples/web`" claim; #701 added one for browser-safe streaming.
- **Log-message docs guidance** — point at the real `docs/` layout from
#677 (`docs/socket_hang_up_econnreset.md`, `docs/howto/`) instead of a
fictional `docs/example-log-message.md`. The example URL in the snippet
now also resolves to a real page (`docs/socket_hang_up_econnreset.md`).
- **New `Skills` section** — documents the repo-root `skills/` directory
(#681, #682, #702): `client-node`'s `prepack` ships it via
`@clickhouse/client`, the `agents.skills` field of
`packages/client-node/package.json` declares which skills are
discoverable, and the `Skills E2E` workflow
(`.github/workflows/e2e-skills.yml`, backed by
`tests/e2e/skills/check.js`) asserts the packaged tarball contains the
declared skills. Routes contributors to `.claude/skills/setup/SKILL.md`
(#705) instead of re-introducing `copilot-setup-steps.yml`.
- **`agents.skills` manifest** — adds `clickhouse-js-node-coding`
alongside `clickhouse-js-node-troubleshooting` so both shipped skills
are discoverable to downstream tooling. `tests/e2e/skills/check.js` is
extended to verify both skills land in the packaged `@clickhouse/client`
tarball.
- **New `Embedded docs` section** — surfaces `docs/` as the preferred
home for pages linked from log messages.
- **CHANGELOG guidance** — aligns with the PR template: entry goes in
the PR description and is folded into `CHANGELOG.md` at release time.

Documentation refresh plus a small manifest/test change to make the
second shipped skill discoverable.

## Checklist

- [x] A human-readable description of the changes was provided to
include in CHANGELOG

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: peter-leonov-ch <209667683+peter-leonov-ch@users.noreply.github.com>
Co-authored-by: Peter Leonov <peter.leonov@clickhouse.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants