tdg-personal/clickhouse-io
ClickHouse database patterns, query optimization, analytics, and data engineering best practices for high-performance analytical workloads.
45
45%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Quality
Discovery
32%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
The description identifies ClickHouse as the target domain and lists broad capability areas, but it reads more like a topic list than an actionable skill description. It lacks a 'Use when...' clause, specific concrete actions, and sufficient trigger terms to reliably distinguish it from general database or analytics skills.
Suggestions
Add an explicit 'Use when...' clause, e.g., 'Use when the user asks about ClickHouse, columnar databases, OLAP queries, or MergeTree engine configuration.'
List specific concrete actions such as 'Designs MergeTree table schemas, writes optimized analytical queries, configures materialized views, and tunes ClickHouse cluster settings.'
Include natural trigger term variations users might say: 'ClickHouse', 'CH', 'columnar database', 'OLAP', 'MergeTree', 'ReplacingMergeTree', 'analytical queries', '.clickhouse'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (ClickHouse database) and some general action areas (query optimization, analytics, data engineering best practices), but doesn't list specific concrete actions like 'write MergeTree table definitions' or 'optimize GROUP BY queries'. | 2 / 3 |
Completeness | Describes what the skill covers at a high level but completely lacks a 'Use when...' clause or any explicit trigger guidance for when Claude should select this skill. Per rubric guidelines, a missing 'Use when...' clause caps completeness at 2, and the 'what' is also weak, so this scores a 1. | 1 / 3 |
Trigger Term Quality | Includes 'ClickHouse', 'query optimization', 'analytics', and 'data engineering' which are relevant keywords, but misses common user variations like 'columnar database', 'OLAP', 'MergeTree', 'materialized views', or 'analytical queries'. | 2 / 3 |
Distinctiveness Conflict Risk | 'ClickHouse' is a distinct technology that provides some niche specificity, but the broad terms 'analytics', 'data engineering best practices', and 'query optimization' could easily overlap with general SQL, database, or data engineering skills. | 2 / 3 |
Total | 7 / 12 Passed |
Implementation
29%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The skill provides extensive, executable ClickHouse examples covering schema design, queries, and data pipelines, which is its primary strength. However, it is significantly too long and monolithic, explains concepts Claude already knows (what ClickHouse is, column-oriented storage), and lacks any workflow sequencing or validation steps. The content would benefit greatly from being split into focused reference files with a concise overview in the main SKILL.md.
Suggestions
Remove the Overview section entirely (Claude knows what ClickHouse is) and trim the 'When to Activate' list to save ~20 lines of unnecessary context.
Split content into separate files: SCHEMA.md (table design), QUERIES.md (analytics patterns), PIPELINES.md (ETL/CDC), and keep SKILL.md as a concise overview with references.
Add validation/verification steps: e.g., after bulk inserts verify row counts, after creating materialized views verify data flows correctly, and add error handling to the TypeScript examples.
Fix the SQL injection vulnerability in the bulk insert TypeScript example by using parameterized queries or the client's built-in insert methods.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The overview section explains what ClickHouse is and lists basic features (column-oriented storage, parallel execution, etc.) that Claude already knows. The 'When to Activate' section is verbose. The document is ~350 lines with significant redundancy (e.g., querying materialized views shown twice with near-identical SQL). Many patterns are generic analytics queries (retention, funnel, cohort) that don't add ClickHouse-specific value beyond standard SQL. | 1 / 3 |
Actionability | The skill provides fully executable SQL and TypeScript code throughout — CREATE TABLE statements, INSERT patterns, monitoring queries, and ETL pipelines are all copy-paste ready with concrete examples. Good/bad patterns are clearly labeled with PASS/FAIL markers. | 3 / 3 |
Workflow Clarity | There are no sequenced multi-step workflows with validation checkpoints. The ETL pattern is pseudocode-level (extractFromPostgres and bulkInsertToClickHouse are undefined). There's no guidance on validating schema changes, verifying data integrity after inserts, or error recovery for any of the operations described. The bulk insert example has SQL injection vulnerabilities with no mention of parameterized queries. | 1 / 3 |
Progressive Disclosure | This is a monolithic wall of content (~350 lines) with no references to external files. Table design, query optimization, insertion patterns, materialized views, monitoring, analytics queries, pipeline patterns, and best practices are all inlined. Content like common analytics queries and pipeline patterns could easily be split into separate reference files. | 1 / 3 |
Total | 6 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 10 / 11 Passed | |
Reviewed
Table of Contents