feat: Add 28 ClickHouse best practices rules and improve documentation#2
Merged
feat: Add 28 ClickHouse best practices rules and improve documentation#2
Conversation
…ctices This PR introduces a comprehensive set of ClickHouse best practices rules following the Vercel agent-skills atomic rules pattern. ## Changes ### New Rules (28 total) **Schema Design (14 rules):** - schema-pk-*: 4 rules for primary key selection - schema-types-*: 5 rules for data type optimization - schema-partition-*: 4 rules for partitioning strategy - schema-json-*: 1 rule for JSON type usage **Query Optimization (8 rules):** - query-join-*: 5 rules for JOIN optimization - query-index-*: 1 rule for skipping indices - query-mv-*: 2 rules for materialized views **Insert Strategy (6 rules):** - insert-batch-*: 1 rule for batch sizing - insert-async-*: 1 rule for async inserts - insert-format-*: 1 rule for data formats - insert-mutation-*: 2 rules for mutation avoidance - insert-optimize-*: 1 rule for OPTIMIZE avoidance ### Updated Files - parser.ts: Added 'insert' to section mapping - _sections.md: Simplified to 3 main sections (schema, query, insert) - SKILL.md: Updated with new rule catalog - README.md: Updated rule counts and structure - AGENTS.md: Regenerated with 28 rules ### Removed - query-use-prewhere.md: Superseded by new query rules All rules link to official ClickHouse Best Practices documentation. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add "What is this?" section explaining agent skills concept - Add table showing all 28 rules by category and impact level - Add Quick Start section with example prompt - Improve formatting and navigation Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- List 10 popular agents with links and config directories - Explain agent-agnostic nature of skills - Document auto-detection behavior and manual setup Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Update SKILL.md to define a clear priority hierarchy:
1. Check skill rules first (authoritative, curated)
2. Fall back to LLM's knowledge if no rule exists
3. Use web search if uncertain
4. Always cite sources
This allows the skill to remain helpful for topics not yet
covered by rules (e.g., projections) while keeping rules
as the primary source of truth.
Also uses agent-agnostic language ("LLM's knowledge" vs
"Claude's knowledge") for compatibility with any AI agent.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds 28 atomic ClickHouse best practice rules organized into schema design, query optimization, and insert strategy categories. The documentation has been restructured with clearer organization, a skills overview table, and improved quick start guidance.
Changes:
- Added 28 new rule files covering PRIMARY KEY selection, data types, JOINs, batching, mutations, partitioning, indices, materialized views, and async inserts
- Reorganized categories from 8 sections to 3 main areas with impact-based prioritization
- Enhanced README with agent compatibility table and clear installation instructions
Reviewed changes
Copilot reviewed 36 out of 36 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
skills/clickhouse-best-practices/rules/*.md |
28 new atomic rule files following standardized template |
skills/clickhouse-best-practices/rules/_template.md |
Updated template format for consistency |
skills/clickhouse-best-practices/rules/_sections.md |
Restructured from 8 to 3 sections with updated descriptions |
skills/clickhouse-best-practices/SKILL.md |
Major rewrite with review procedures, output format, and category reference |
skills/clickhouse-best-practices/README.md |
Simplified with table-based overview and trigger phrases |
skills/clickhouse-best-practices/AGENTS.md |
Regenerated compiled guide with all new rules |
packages/clickhouse-best-practices-build/src/parser.ts |
Updated section mapping for new 3-category structure |
README.md |
Enhanced with skills overview table, quick start, and agent compatibility |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
pjhampton
approved these changes
Jan 23, 2026
Comment on lines
+150
to
+162
| **When to add partitioning:** | ||
|
|
||
| | Need | Add Partitioning? | | ||
|
|
||
| |------|-------------------| | ||
|
|
||
| | Time-based data retention | Yes | | ||
|
|
||
| | Archive old data to cold storage | Yes | | ||
|
|
||
| | Query performance on time ranges | Maybe (test first) | | ||
|
|
||
| | No specific lifecycle needs | No | |
Member
There was a problem hiding this comment.
Not that it probably matters for the LLM, but this table isn't rendering properly likely because of the new lines between rows.
| ### Insert Strategy - Async (HIGH) | ||
|
|
||
| - `insert-async-small-batches` - Async inserts for high-frequency small batches | ||
| - `insert-format-native` - Native format for best performance |
Member
There was a problem hiding this comment.
Should this be named (?)
insert-async-format-native
pjhampton
added a commit
that referenced
this pull request
Jan 23, 2026
Adds a daily CI job that checks all external HTTP/HTTPS links in the skills directory to ensure they remain valid over time. ## Motivation External links can break over time due to: - Domain changes or site restructuring - Deprecated documentation pages - Service shutdowns - URL typos during authoring This automated check helps maintain documentation quality by detecting broken links before users encounter them. When run on #2 ``` $ bun src/check-external-links.ts Checking external links... Skill directory: /Users/pjhampton/workspace/agent-skills/skills/clickhouse-best-practices Found 32 files to scan Found 13 unique external links Checked 5/13 links... Checked 10/13 links... Checked 13/13 links... ================================================================================ External Links Check Summary ================================================================================ ┌─────────────────────────────────────────────────────────────────────────────┐ │ URL │ Status │ Source │ ├──────────────────────────────────────────────────────────┼────────┼─────────┤ │ https://clickhouse.com/docs │ 200 ✓ │ ...data.json │ │ https://clickhouse.com/docs/best-practices │ 200 ✓ │ README.md │ │ https://clickhouse.com/docs/best-practices/avoid-muta... │ 200 ✓ │ ...delete.md │ │ https://clickhouse.com/docs/best-practices/avoid-opti... │ 200 ✓ │ ...-final.md │ │ https://clickhouse.com/docs/best-practices/choosing-a... │ 200 ✓ │ ...ecycle.md │ │ https://clickhouse.com/docs/best-practices/choosing-a... │ 200 ✓ │ ...rderby.md │ │ https://clickhouse.com/docs/best-practices/minimize-o... │ 200 ✓ │ ...before.md │ │ https://clickhouse.com/docs/best-practices/select-dat... │ 200 ✓ │ ...llable.md │ │ https://clickhouse.com/docs/best-practices/selecting-... │ 200 ✓ │ ...h-size.md │ │ https://clickhouse.com/docs/best-practices/use-data-s... │ 200 ✓ │ ...ndices.md │ │ https://clickhouse.com/docs/best-practices/use-json-w... │ 200 ✓ │ ...to-use.md │ │ https://clickhouse.com/docs/best-practices/use-materi... │ 200 ✓ │ ...shable.md │ │ https://github.com/ClickHouse/ClickHouse │ 200 ✓ │ ...data.json │ └──────────────────────────────────────────────────────────┴────────┴─────────┘ Summary: 13 links checked, 13 passed, 0 failed ✓ All 13 external links are valid ```
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Rules Added
Test plan
🤖 Generated with Claude Code