Name: writing-clickhouse-queries
Rating: 68.8 (1 reviews)
Author: PostHog

writing-clickhouse-queries

Guide for writing performant ClickHouse queries in PostHog product code. Use when writing HogQL query runners, designing a ClickHouse table for a new product, adding materialized columns or skip indexes, or choosing a row ID format. For optimizing an existing query that is already too slow, use `/optimizing-clickhouse-and-hogql-queries` instead.

Quality

83%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

75%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A well-structured, concise routing skill that clearly dispatches to authoritative external docs and distinguishes itself from the sibling optimization skill. Its inline actionability is limited because the executable guidance lives in non-bundled external docs rather than in the skill itself.

Suggestions

Add a minimal inline quick-start snippet (e.g., a skeleton QueryRunner subclass or a sample CREATE TABLE with a row ID format) so the body is actionable even before opening the external docs.

Move or mirror the key referenced docs into ./references/ so the skill is self-contained and the paths resolve reliably.

Consolidate the duplicate optimization redirect (stated in both the opening paragraph and the 'When to use' section) into one place to tighten the body further.

Dimension	Reasoning	Score
Conciseness	Lean routing body that assumes Claude's competence — no concept explanations, no padding, every line earns its place by pointing to a specific doc or stating a when-to-use condition.	5 / 5
Actionability	Provides concrete file-path pointers ('Read docs/.../clickhouse-queries-new-products.md') and a specific 'When to use' list, but the actual executable query-writing guidance is delegated to external docs not present in the bundle, leaving the body itself without inline code or commands.	3 / 5
Workflow Clarity	Clear routing sequence — boundary redirect, read the authoritative guide, pull in related docs, when-to-use/when-not-to-use conditions — appropriate for a simple dispatch skill with no risky operations needing validation.	4 / 5
Progressive Disclosure	Clean overview with well-signaled one-level-deep references to related docs; however the referenced docs live outside the skill bundle (../../../docs/published/...), so navigation depends on paths that may not be reliably co-located with the skill.	4 / 5
	Total	16 / 20 Passed

Description

92%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong, specific description that clearly answers both what the skill does and when to use it, with concrete trigger terms and an explicit boundary against the sibling optimization skill. Minor keyword gaps (e.g., projections) keep trigger quality just below maximum.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — 'writing HogQL query runners', 'designing a ClickHouse table for a new product', 'adding materialized columns or skip indexes', 'choosing a row ID format' — giving comprehensive coverage of the skill's capabilities.	5 / 5
Completeness	Explicitly states what ('Guide for writing performant ClickHouse queries in PostHog product code') and when ('Use when writing HogQL query runners, designing a ClickHouse table...'), with concrete trigger phrases and a boundary redirect.	5 / 5
Trigger Term Quality	Strong domain-natural terms a PostHog engineer would say ('HogQL query runners', 'materialized columns', 'skip indexes', 'row ID format'); a few natural terms like 'projections' or 'ALTER' that appear in the body are absent here.	4 / 5
Distinctiveness Conflict Risk	Narrow PostHog/ClickHouse niche with explicit redirection of optimization work to '/optimizing-clickhouse-and-hogql-queries', giving clear distinct triggers and minimal conflict risk.	5 / 5
	Total	19 / 20 Passed

Validation

93%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
relative_links	Relative link issues: 6 suspicious	Warning

	Total	15 / 16 Passed

Repository: PostHog/posthog
Path: .agents/skills/writing-clickhouse-queries/SKILL.md
Commit: 6fca5f8

Reviewed: 3 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.