tinybird-python-sdk-guidelines

Descripción general de la skill tinybird-python-sdk-guidelines

Para qué sirve esta skill

La skill tinybird-python-sdk-guidelines te ayuda a trabajar con recursos de Tinybird en Python usando tinybird-sdk. Es especialmente útil cuando necesitas definir datasources, endpoints, conexiones o acceso de cliente en un proyecto de Tinybird orientado al código, sobre todo en flujos de desarrollo backend e ingesta de datos.

Quién debería usarla

Usa la skill tinybird-python-sdk-guidelines si estás:

• empezando un nuevo proyecto de Tinybird en Python
• migrando archivos heredados .datasource / .pipe a Python
• integrando Tinybird en un servicio backend
• construyendo consultas, pipelines o rutas de ingesta que deban quedarse del lado del servidor

Qué hace mejor que un prompt genérico

Esta skill no se limita a “escribir código de Tinybird”. También te da las reglas operativas detrás del código: cómo se resuelve la configuración, qué comandos de CLI importan, cómo estructurar los archivos de cliente y dónde suelen producirse los errores de despliegue. Por eso tinybird-python-sdk-guidelines resulta más útil cuando el riesgo principal no es la sintaxis, sino una mala configuración, un manejo inseguro de tokens o el uso del destino de desarrollo equivocado.

Cómo usar la skill tinybird-python-sdk-guidelines

Instálala y actívala

Instala la skill tinybird-python-sdk-guidelines con el gestor de skills del repositorio y luego apunta tu agente a la ruta de la skill:
npx skills add tinybirdco/tinybird-agent-skills --skill tinybird-python-sdk-guidelines

Si tu flujo de trabajo permite leer directamente los archivos de la skill, empieza por skills/tinybird-python-sdk-guidelines/SKILL.md.

Dale el tipo de tarea correcto

El uso de tinybird-python-sdk-guidelines funciona mejor cuando tu prompt incluye:

• el tipo de recurso: datasource, endpoint, client, connection, copy pipe o migración
• el contexto de ejecución: desarrollo local, branch mode o despliegue en producción
• la forma de entrada: esquema de tabla, SQL, parámetros de API, secretos o estructura de archivos
• la salida esperada: una definición en Python, un archivo de configuración o un plan de despliegue

Ejemplo de prompt sólido:
“Crea un datasource y un endpoint de Tinybird en Python para seguimiento de eventos. Usa tinybird-sdk, incluye tinybird.config.json y muestra cómo consultarlo desde lib/client.py. Asume branch dev mode y uso exclusivo de tokens del lado del servidor.”

Lee los archivos en este orden

Para un comportamiento práctico de la guía tinybird-python-sdk-guidelines, lee:

1. SKILL.md para el alcance y la decisión de instalación
2. rules/getting-started.md para la configuración del proyecto
3. rules/configuration.md para la configuración y la resolución de tokens
4. rules/defining-datasources.md y rules/defining-endpoints.md para las definiciones principales
5. rules/client.md y rules/cli-commands.md para el uso y el flujo de build/deploy

Si vas a hacer integraciones externas, añade rules/connections.md, rules/materialized-views.md y rules/copy-sink-pipes.md.

Flujo de trabajo que suele dar mejores resultados

Usa esta secuencia:

1. define el objeto de Tinybird que necesitas
2. confirma la configuración y dev_mode
3. genera o actualiza lib/*.py
4. ejecuta tinybird build antes de desplegar
5. usa tinybird deploy solo después de validar la estructura local

Esto importa porque las decisiones de instalación de tinybird-python-sdk-guidelines suelen depender de si quieres ayuda para generar código o un flujo real de despliegue en Tinybird.

Preguntas frecuentes de la skill tinybird-python-sdk-guidelines

¿Es solo para proyectos en Python?

Sí. La skill tinybird-python-sdk-guidelines está pensada alrededor de tinybird-sdk y definiciones de recursos primero en Python. Si tu proyecto usa sobre todo archivos SQL o la interfaz de Tinybird, quizá te convenga un flujo distinto y más simple.

¿Necesito experiencia previa con Tinybird?

No, pero sí necesitas saber qué quieres construir: un datasource, un endpoint, un cliente de ingesta o una conexión. Las personas principiantes suelen avanzar más rápido si aportan un esquema de ejemplo o una consulta en lugar de pedir una arquitectura amplia de Tinybird.

¿En qué se diferencia de un prompt normal?

Un prompt normal puede generar código, pero la skill tinybird-python-sdk-guidelines también incorpora restricciones específicas de Tinybird: prioridad de archivos de configuración, manejo de tokens del lado del servidor, comportamiento de despliegue entre branch y main, y el modelo de build/deploy de la CLI. Eso reduce el ensayo y error.

¿Cuándo no debería usarla?

No uses tinybird-python-sdk-guidelines para flujos de tokens del lado del navegador, diseño genérico de APIs en Python o tareas de analítica que no involucren recursos de Tinybird. Tampoco es una buena opción si solo quieres una consulta SQL puntual sin estructura de proyecto en Python.

Cómo mejorar la skill tinybird-python-sdk-guidelines

Indica el objeto exacto de Tinybird y el entorno

El mejor uso de tinybird-python-sdk-guidelines parte de entradas precisas. Di si necesitas:

• define_datasource, define_endpoint, define_connection o configuración de client
• comportamiento de dev_mode en branch o en local
• migración desde archivos heredados o scaffolding nuevo
• un solo recurso o la estructura completa del proyecto

Una solicitud vaga como “configura Tinybird” lleva a una salida genérica. Una solicitud más sólida como “define un datasource para eventos de clickstream con t.date_time(), t.string() y una clave de ordenación de merge tree, y luego muestra el archivo del client” le da al modelo la estructura suficiente para hacer un trabajo útil.

Expón tus restricciones desde el principio

Incluye cualquier cosa que pueda bloquear la adopción:

• requisitos de manejo de secretos
• estructura de carpetas existente como lib/ o tinybird/
• destino de despliegue y si main está protegido
• si necesitas tinybird build, tinybird dev o tinybird migrate

Estos detalles importan porque la salida de la guía tinybird-python-sdk-guidelines es más valiosa cuando evita valores predeterminados inseguros y elige la ruta correcta de CLI.

Itera desde el esquema hasta código desplegable

Si el primer resultado está cerca, pero incompleto, mejóralo aportando:

• filas de ejemplo
• tipos de columna y campos nulos
• parámetros del endpoint y valores por defecto
• la lógica SQL exacta o el nombre de la fuente de datos

Luego pide una segunda pasada que revise la configuración, los imports del client y la preparación para build/deploy. Es la forma más rápida de convertir un borrador en algo que encaje de verdad en un repo de Tinybird.