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.

Related Skills

Skill: Inngest Agents

by Inngest

New

Build crash-safe AI agents on AgentKit and step.ai — durable tool calls, human-in-the-loop approval, realtime progress, and when not to reach for an agent loop at all.

Development
2 views

Skill: Inngest Durable Functions

by Inngest

New

Inngest's durable-execution playbook as an agent skill — steps and memoisation, event and cron triggers, idempotency, cancellation, retries and non-retriable errors.

Development
2 views

Skill: Temporal Developer

by Temporal

New

Temporal's official skill for building durable workflows — SDK patterns across seven languages, plus the determinism rules that decide whether a workflow survives a replay.

Development
6 views
Browse all skills →