Forked from ClickHouse/agent-skills, which provides 28 battle-tested rules for schema design, query optimization, and data ingestion — all in ClickHouse SQL. We extended every rule with MooseStack TypeScript and Python examples so your agents apply the same discipline when writing application code, not just raw DDL.
Teams use MooseStack + ClickHouse to ship analytics features inside their applications — the kind of features where performance, schema design, and data modeling directly impact the end user. This skill makes sure your agents get those decisions right from the start.
Fast, customer-facing dashboards. Your users expect interactive charts and filters that respond in milliseconds, not seconds. When analytical queries outgrow your transactional database, moving them to ClickHouse yields 10–100x faster dashboards — but only if the schema is designed for your actual access patterns. This skill teaches agents to choose the right orderByFields, partitioning, and types so the data model performs well from day one.
Data-connected chat in your app. LLMs can now query your database through MCP, turning natural language into live analytics. The quality of those answers depends on how your data is modeled: clean schemas, well-chosen types, and materialized views that pre-aggregate the right dimensions. This skill ensures agents build chat-ready data models that return fast, accurate results.
Agents that write ClickHouse SQL benefit from the upstream skill. Agents that define data models in TypeScript or Python — declaring OlapTable, IngestPipeline, MaterializedView — need the same guidance translated into their language.
This skill is one layer of what we call an agentic harness: the infrastructure interface that lets agents build on and operate your data stack correctly. MooseStack provides the declarative framework; this skill teaches agents to use it well.
npx skills add 514-labs/agent-skillsWorks with Claude Code, Cursor, Copilot, Windsurf, Gemini CLI, Codex, and 20+ other agents.
28 rules, each with ClickHouse SQL + MooseStack TypeScript + MooseStack Python examples:
| Category | Rules | Impact | e.g. |
|---|---|---|---|
Key ordering / orderByFields |
4 | CRITICAL | order columns low-to-high cardinality, prioritize filter columns |
| Type selection | 5 | CRITICAL | prefer native types, minimize bit-width, avoid Nullable |
| JOIN optimization | 5 | CRITICAL | filter before joining, ANY for single matches |
| Insert batching | 1 | CRITICAL | 10K-100K rows per batch |
| Mutation avoidance | 2 | CRITICAL | no ALTER TABLE UPDATE/DELETE |
| Partitioning | 4 | HIGH | lifecycle management, keep cardinality under 1,000 |
| Skipping indices | 1 | HIGH | bloom filters for non-ORDER BY filters |
| Materialized views | 2 | HIGH | incremental for real-time, refreshable for batch |
| Async inserts | 2 | HIGH | high-frequency small batches |
| OPTIMIZE avoidance | 1 | HIGH | let merges happen naturally |
| JSON usage | 1 | MEDIUM | use JSON type for dynamic schemas |
Browse the rules: skills/clickhouse-best-practices/ | Human-friendly overview: SKILL.md
Docs: MooseStack | ClickHouse
Here's a sample of our source data [paste schema or CSV header]. Our queries filter heavily by region and time range. Using the
clickhouse-best-practices-ts-pyskill, create an optimized TypeScript data model with the rightorderByFields, partitioning, and type annotations. Usemoose queryto validate the table performs well for those access patterns.
Using the
clickhouse-best-practices-ts-pyskill, review thisOlapTabledefinition against the queries in our Next.js frontend atapp/dashboard/. Are theorderByFieldsin the right order given actual filter and GROUP BY patterns? Should any string columns beLowCardinality? Is Nullable justified on these fields?
I need to track order line items with frequent updates to fulfillment status. Using the
clickhouse-best-practices-ts-pyskill, what table engine and data model should I use to avoid mutations? Show me the TypeScript and Python versions.
Here's my Postgres data model [paste schema]. Using the
clickhouse-best-practices-ts-pyskill, translate it to an optimized ClickHouse TypeScript model — denormalize where it makes sense for OLAP reads. Then create a MaterializedView for tracking sub-brand performance by region and month.
You don't strictly need to name the skill — most agents will activate it automatically when they see ClickHouse or MooseStack context. We like to call it explicitly when we want a formal review against the full ruleset.
For best results, have moose dev running and connect the MooseStack MCP server to your agent. This lets the agent query your local ClickHouse, inspect infrastructure, and validate its recommendations against real data.
The installer auto-detects which agents you have. Skills are agent-agnostic — same skill, every assistant:
| Agent | Config Directory |
|---|---|
| Claude Code | .claude/skills/ |
| Cursor | .cursor/skills/ |
| Windsurf | .windsurf/skills/ |
| GitHub Copilot | .github/skills/ |
| Gemini CLI | .gemini/skills/ |
| Cline | .cline/skills/ |
| Codex | .codex/skills/ |
| Goose | .goose/skills/ |
| Roo Code | .roo/skills/ |
| OpenHands | .openhands/skills/ |
And 13 more.
The ClickHouse team's agent-skills repo did the hard work of codifying ClickHouse best practices into agent-consumable rules. This project wouldn't exist without it.
Apache 2.0 — see LICENSE.