chore: Add Claude Code agent skills and update CLAUDE.md#25
chore: Add Claude Code agent skills and update CLAUDE.md#25heavycrystal wants to merge 1 commit intomainfrom
Conversation
Add ClickHouse best practices skill (https://github.com/clickhouse/agent-skills) covering schema design, query optimization, and data ingestion. Update CLAUDE.md with schema immutability policy and reference projects guidelines.
There was a problem hiding this comment.
Pull request overview
Adds a ClickHouse best-practices “skill” for agents and updates contributor guidance around ClickHouse schema changes and how to use external reference projects.
Changes:
- Adds a new
.claude/skills/clickhouse-best-practicesskill with rule docs covering schema, query, and ingestion best practices. - Updates
CLAUDE.mdwith a ClickHouse schema immutability/migration policy and tighter guidance on using external reference repos.
Reviewed changes
Copilot reviewed 31 out of 31 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
CLAUDE.md |
Adds ClickHouse schema immutability guidance and updates reference-project usage policy. |
.claude/skills/clickhouse-best-practices/SKILL.md |
Introduces the skill manifest and usage/review procedures for ClickHouse guidance. |
.claude/skills/clickhouse-best-practices/AGENTS.md |
Adds a compiled “all rules” document for quick scanning. |
.claude/skills/clickhouse-best-practices/rules/* |
Adds individual rule markdown files for schema/query/insert best practices. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| license: Apache-2.0 | ||
| metadata: | ||
| author: ClickHouse Inc | ||
| version: "0.3.0" |
There was a problem hiding this comment.
The skill manifest declares version 0.3.0, but AGENTS.md declares Version 0.1.0. These should match to avoid confusion when referencing the skill/version in reviews. Consider updating AGENTS.md’s header to the same version as SKILL.md (or vice versa) and keep the ClickHouse version/date consistent with that release.
| version: "0.3.0" | |
| version: "0.1.0" |
| @@ -0,0 +1,1572 @@ | |||
| # ClickHouse Best Practices | |||
|
|
|||
| **Version 0.1.0** | |||
There was a problem hiding this comment.
This version marker conflicts with the version in SKILL.md (0.3.0). Align the declared version across both documents so users can reliably identify which rule set they’re reading.
| **Version 0.1.0** | |
| **Version 0.3.0** |
| | Sequential IDs | UInt32/UInt64 | String | | ||
| | UUIDs | UUID | String | | ||
| | Status/Category | Enum8 or LowCardinality(String) | String | | ||
| | Timestamps | DateTime | DateTime64, String | |
There was a problem hiding this comment.
The quick reference implies DateTime64 should generally be avoided for timestamps. That’s overly broad and can be misleading: DateTime64 is appropriate when sub-second precision is required. Consider changing this row to recommend DateTime for second precision and DateTime64 when higher precision is needed (while still discouraging String).
| | Timestamps | DateTime | DateTime64, String | | |
| | Timestamps | DateTime (seconds) or DateTime64 (sub-second) | String | |
| ```python | ||
| # Use Native format for best performance | ||
| client.execute("INSERT INTO events VALUES", data, settings={'input_format': 'Native'}) |
There was a problem hiding this comment.
This Python snippet is likely inaccurate for many ClickHouse clients: Native is a wire/binary format typically specified via FORMAT Native (or by using the native protocol), and many drivers won’t accept an input_format setting like this. Consider rewriting the example to a generally correct form (e.g., INSERT ... FORMAT Native with a client capable of sending Native-formatted data, or provide a clickhouse-client example) to prevent readers from copying a non-working pattern.
| ```python | |
| # Use Native format for best performance | |
| client.execute("INSERT INTO events VALUES", data, settings={'input_format': 'Native'}) | |
| ```bash | |
| # Use Native format for best performance with clickhouse-client | |
| clickhouse-client --query="INSERT INTO events FORMAT Native" < events.native |
2 participants
Add ClickHouse best practices skill (https://github.com/clickhouse/agent-skills) covering schema design, query optimisation, and data ingestion. Update CLAUDE.md with schema immutability policy and reference projects guidelines.