Skip to content
Tinybird Best Practices

Tinybird Best PracticesSkill

by Tinybird
Added to Onei
Repository Docs
markdown Development

Summary

Tinybird's own datafile and SQL rules for coding agents — datasources, pipes, endpoints, materialized views, deduplication and query optimisation.

Features

  • House rules for .datasource, .pipe and .connection files
  • SQL and endpoint optimisation guidance (filter early, project narrow, defer expensive work)
  • Materialized view patterns, including join prefiltering
  • Deduplication patterns and engine selection (MergeTree / AggregatingMergeTree)
  • Local vs Cloud build semantics for the tb CLI

Install This Skill

Add this skill to your favorite AI agent in a few steps.

Any AI agent

This skill is plain instructions — it works with any assistant that accepts custom instructions or system prompts.

  1. Copy the skill content with the button below.
  2. Paste it into your agent's instruction file or system prompt (for example AGENTS.md, .cursorrules, or a custom instructions field).
  3. Ask the agent to apply the skill whenever the task matches.

Skill Content

Markdown Content

Copy this content and use it with your preferred AI agent

---
name: tinybird
description: Tinybird file formats, SQL rules, optimization patterns, and best practices for datasources, pipes, endpoints, and materialized views.
---

# Tinybird Best Practices

Guidance for Tinybird file formats, SQL rules, optimization patterns, and data modeling. Use this skill when creating or editing Tinybird datafiles.

## When to Apply

- Creating or updating Tinybird resources (.datasource, .pipe, .connection)
- Writing or optimizing SQL queries
- Designing endpoint schemas and data models
- Organizing project structure and data layers
- Working with materialized views or copy pipes
- Implementing deduplication patterns
- Reviewing or refactoring Tinybird project files

## Rule Files

- `rules/project-files.md`
- `rules/build-deploy.md`
- `rules/datasource-files.md`
- `rules/pipe-files.md`
- `rules/endpoint-files.md`
- `rules/materialized-files.md`
- `rules/materialized-join-prefilter.md`
- `rules/sink-files.md`
- `rules/copy-files.md`
- `rules/connection-files.md`
- `rules/sql.md`
- `rules/endpoint-optimization.md`
- `rules/tests.md`
- `rules/deduplication-patterns.md`

## Quick Reference

- Project local files are the source of truth.
- Build target comes from `tinybird.config.json` `dev_mode` (`local` or `branch`).
- `tb deploy` targets Tinybird Cloud production.
- Commands like `tb sql` and `tb logs` default to local unless `--cloud` or `--branch=<branch-name>` is set.
- SQL is SELECT-only with Tinybird templating rules and strict parameter handling.
- Use MergeTree by default; AggregatingMergeTree for materialized targets.
- Filter early, select only needed columns, push complex work later in the pipeline.

Usage Instructions

Learn how to use this skill with different AI agents.

Generic Instructions

Install with the Agent Skills CLI:

npx skills add tinybirdco/tinybird-agent-skills

Or copy skills/tinybird-best-practices/ into your project's skills directory (.claude/skills/ for Claude Code, .cursor/skills/ for Cursor, .agents/skills/ for Codex). The agent loads it automatically when it detects Tinybird datafiles in the repo.

Description

The official agent skill from the Tinybird team, covering how to write and review the datafiles a Tinybird project is made of.

Tinybird projects are defined in plain text — .datasource, .pipe and .connection files that tb deploy pushes to Tinybird Cloud. That makes them exactly the kind of artefact a coding agent will happily generate, and exactly the kind where a small mistake (the wrong engine, an unfiltered join in a materialized view, a template parameter handled loosely) shows up as a slow endpoint or a wrong number rather than a syntax error.

The skill loads Tinybird's house rules for each file type and for the SQL inside them: MergeTree by default and AggregatingMergeTree for materialized targets; filter early and select only the columns you need; push expensive work later in the pipeline; SELECT-only SQL with strict parameter handling in Tinybird's templating syntax. It carries fourteen focused rule files an agent pulls in on demand — project layout, build and deploy, each datafile type, materialized-view join prefiltering, endpoint optimisation, tests and deduplication patterns — plus the local-versus-cloud distinction that trips people up (tb sql and tb logs default to local unless --cloud or --branch is passed, and dev_mode in tinybird.config.json decides the build target).

Use it whenever an agent is creating or refactoring Tinybird resources, designing an endpoint schema, or reviewing a project's SQL.

Install

Related Skills

Skill: BigQuery Basics

by Google

Google's official BigQuery skill — datasets, tables, jobs and SQL from the bq CLI, plus the reference set for IAM, Terraform, change history and continuous queries.

Development

Skill: DuckDB Query

by DuckDB

Featured

Run SQL — or a plain-English question — against DuckDB databases, CSV, Parquet, JSON and Excel files, with schema inspection and error recovery built in.

AnalyticsCSV
65 views

Skill: ClickHouse Best Practices

by ClickHouse Inc

ClickHouse's official agent skill: 31 rules for primary keys, data types, JOINs, batching and partitioning that an agent must check and cite before advising on a schema or query.

Development

Skill: EF Core Query Optimization

by .NET Team at Microsoft

Make slow Entity Framework Core queries fast — read the generated SQL first, fix N+1s, cartesian Include explosions and non-sargable predicates, then re-measure one change at a time.

Development
Browse all skills →