skilld
All skills
clickhouse avatar

/clickhouse-architecture-advisor

@5e162d6 official
by clickhouseclickhouse/agent-skills543 stars
39

MUST USE when designing ClickHouse architectures, selecting between ingestion or modeling patterns, or translating best practices into workload-specific system designs. Complements clickhouse-best-practices with decision frameworks and explicit provenance labels.

Ask your Agent

Use this Skill: https://skilld.dev/gh/clickhouse/agent-skills/clickhouse-architecture-advisor

This session only. Nothing lands on disk.

AGENTS.md

≈564 tokens on demand. Your agent reads this file only when SKILL.md points to it.

ClickHouse Architecture Advisor

Version 0.1.0
ClickHouse Inc
April 2026
ClickHouse 24.1+

Abstract

This skill complements clickhouse-best-practices by adding a workload-aware architecture layer for ClickHouse. It is optimized for advisory, workshop, and system design workflows where a user needs more than a rule check. It provides decision frameworks for ingestion strategy, time-series partitioning, enrichment paths, late-arriving data, and real-time pre-aggregation.

Core principle

Official documentation is the source of truth. Every recommendation must be labeled as:

  • official
  • derived
  • field

Decision areas

1. Ingestion strategy

Use when deciding between:

  • direct inserts
  • async inserts
  • Kafka engine + MV
  • upstream buffering

2. Time-series partitioning

Use when deciding:

  • whether to partition
  • partition granularity
  • how retention and TTL affect design
  • how to avoid excessive partition counts

3. Enrichment path selection

Use when deciding between:

  • runtime JOINs
  • dictionaries
  • denormalization
  • materialized enrichment

4. Late-arriving data and mutable state

Use when reasoning about:

  • immutable append-only events
  • latest-state queries
  • replacing or collapsing semantics
  • whether frequent mutations should be avoided

5. Real-time pre-aggregation

Use when deciding:

  • raw-only design
  • incremental materialized views
  • refreshable MVs
  • rollup tables

Output standard

A valid architecture response should include:

  • workload summary
  • key decisions
  • recommendations with provenance labels
  • suggested target architecture
  • example DDL or SQL
  • validation approach

Required recommendation schema

See schemas/recommendation_schema.yaml.

Rule index

  1. decision-ingestion-strategy
  2. decision-partitioning-timeseries
  3. decision-join-enrichment
  4. decision-late-arriving-upserts
  5. decision-real-time-preaggregation

Implementation notes

This skill is intentionally narrow:

  • it does not replace low-level rule enforcement
  • it does not make commercial recommendations
  • it does not claim field heuristics are official policy

Its purpose is to translate documented ClickHouse capabilities into workload-specific architecture decisions.

Source: SKILL.md on GitHub

Third-party checks

No alerts17d4 checks · Risk SAFE
  • Gen Agent Trust Hub17d

    The skill is a safe architectural advisor for ClickHouse workloads. It provides structured decision frameworks for ingestion, partitioning, and schema design based on official documentation. No malicious patterns, data exfiltration, or dangerous execution triggers were detected.

  • Socket17d

    No alerts

  • Snyk17d

    Risk: LOW · No issues

  • ZeroLeaks5mo

    Score: 93/100 · 2 sections analyzed

Provenance

Signed by skilld at 5e162d6. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 days ago.

Activeupdated 6 months ago

Capability

metadata
{
  "author": "ClickHouse Inc",
  "version": "0.1.0"
}

Topics

  • clickhouse
  • architecture
  • olap
  • ingestion
  • time-series
  • schema-design
  • partitioning
  • joins
  • telemetry

README badge

README badge for clickhouse/agent-skills/clickhouse-architecture-advisor

What it does

Guides ClickHouse architecture decisions for specific workloads—observability, analytics, IoT, financial services—by mapping workload shape to ingestion, partitioning, and join strategies with official documentation links. Classifies recommendations by provenance (official, derived, field) to separate documented behavior from heuristic field guidance.

Generated from the current SKILL.md.

Frequently asked

Does this skill replace the clickhouse-best-practices skill?
No. This skill complements clickhouse-best-practices by adding workload-aware decision frameworks and provenance labels. Official documentation remains the source of truth for both.
What workload types does this skill cover?
Observability, security/SIEM, product analytics, IoT/telemetry, market data/financial services, and mixed OLAP with point-lookups. Each has scenario-specific rule files for ingestion, time-series retention, enrichment, and late-arriving events.
How does this skill distinguish between official, derived, and field guidance?
Official recommendations are directly from ClickHouse docs. Derived recommendations follow logically from documented behavior. Field recommendations are experience-based and include a disclaimer that they are heuristic and workload-dependent.
What should I do if a recommendation is uncertain?
The skill explicitly states when a recommendation is uncertain rather than presenting it as confident guidance.

Generated from the current SKILL.md. These answers refresh after source changes.