tinybird-python-sdk-guidelines

Overview of tinybird-python-sdk-guidelines skill

What this skill is for

The tinybird-python-sdk-guidelines skill helps you work with Tinybird resources in Python using tinybird-sdk. It is most useful when you need to define datasources, endpoints, connections, or client access in a code-first Tinybird project, especially for backend development and data ingestion workflows.

Who should use it

Use the tinybird-python-sdk-guidelines skill if you are:

• starting a new Tinybird Python project
• migrating legacy .datasource / .pipe files to Python
• wiring Tinybird into a backend service
• building queries, pipelines, or ingestion paths that must stay server-side

What it does better than a generic prompt

This skill is not just “write Tinybird code.” It gives you the operational rules behind the code: how config is resolved, which CLI commands matter, how to structure client files, and where deployment mistakes usually happen. That makes tinybird-python-sdk-guidelines more useful when the main risk is not syntax, but misconfiguration, unsafe token handling, or using the wrong dev target.

How to Use tinybird-python-sdk-guidelines skill

Install and activate it

Install the tinybird-python-sdk-guidelines skill with the repo’s skill manager, then point your agent at the skill path:
npx skills add tinybirdco/tinybird-agent-skills --skill tinybird-python-sdk-guidelines

If your workflow supports reading skill files directly, start from skills/tinybird-python-sdk-guidelines/SKILL.md.

Give it the right kind of task

The tinybird-python-sdk-guidelines usage works best when your prompt includes:

• the resource type: datasource, endpoint, client, connection, copy pipe, or migration
• the runtime context: local dev, branch mode, or production deploy
• your input shape: table schema, SQL, API params, secrets, or file layout
• the expected output: a Python definition, a config file, or a deployment plan

Example of a strong prompt:
“Create a Tinybird datasource and endpoint in Python for event tracking. Use tinybird-sdk, include tinybird.config.json, and show how to query it from lib/client.py. Assume branch dev mode and server-side token usage only.”

Read the files in this order

For practical tinybird-python-sdk-guidelines guide behavior, read:

1. SKILL.md for scope and install decision
2. rules/getting-started.md for project setup
3. rules/configuration.md for config and token resolution
4. rules/defining-datasources.md and rules/defining-endpoints.md for core definitions
5. rules/client.md and rules/cli-commands.md for usage and build/deploy flow

If you are doing external integrations, add rules/connections.md, rules/materialized-views.md, and rules/copy-sink-pipes.md.

Workflow that usually produces the best result

Use this sequence:

1. define the Tinybird object you need
2. confirm config and dev_mode
3. generate or update lib/*.py
4. run tinybird build before deploy
5. use tinybird deploy only after the local shape is validated

This matters because tinybird-python-sdk-guidelines install decisions often hinge on whether you want code generation help or an actual Tinybird deployment workflow.

tinybird-python-sdk-guidelines skill FAQ

Is this only for Python projects?

Yes. The tinybird-python-sdk-guidelines skill is built around tinybird-sdk and Python-first resource definitions. If your project is mostly SQL files or the Tinybird UI, a different workflow may be simpler.

Do I need Tinybird experience first?

No, but you do need to know what you are trying to build: datasource, endpoint, ingestion client, or connection. Beginners usually succeed faster if they provide a sample schema or query instead of asking for a broad Tinybird architecture.

How is this different from a normal prompt?

A normal prompt may generate code, but the tinybird-python-sdk-guidelines skill also encodes Tinybird-specific constraints: config file priority, server-side token handling, branch vs main deploy behavior, and the CLI build/deploy model. That reduces trial and error.

When should I not use it?

Do not use tinybird-python-sdk-guidelines for browser-side token flows, generic Python API design, or analytics tasks that do not involve Tinybird resources. It is also a poor fit if you only want a one-off SQL query with no Python project structure.

How to Improve tinybird-python-sdk-guidelines skill

Provide the exact Tinybird object and environment

The best tinybird-python-sdk-guidelines usage comes from precise inputs. Say whether you need:

• define_datasource, define_endpoint, define_connection, or client setup
• dev_mode branch or local behavior
• migration from legacy files or fresh scaffolding
• one resource or a whole project layout

A vague request like “set up Tinybird” leads to generic output. A stronger request like “define a datasource for clickstream events with t.date_time(), t.string(), and a merge tree sorting key, then show the client file” gives the model enough structure to do useful work.

Tell it your constraints upfront

Include anything that can block adoption:

• secret handling requirements
• existing folder layout such as lib/ or tinybird/
• deployment target and whether main is protected
• whether you need tinybird build, tinybird dev, or tinybird migrate

These details matter because tinybird-python-sdk-guidelines guide output is most valuable when it avoids unsafe defaults and picks the right CLI path.

Iterate from schema to deployable code

If the first result is close but incomplete, improve it by supplying:

• sample rows
• column types and nullable fields
• endpoint parameters and defaults
• the exact SQL logic or data source name

Then ask for a second pass that checks config, client imports, and build/deploy readiness. This is the fastest way to turn a draft into something that fits a real Tinybird repo.