tinybird-cli-guidelines

tinybird-cli-guidelines 技能概覽

tinybird-cli-guidelines 技能是一份實用指南，幫助你使用 Tinybird CLI（tb）時減少猜測造成的錯誤，並做出更好的工作流程決策。它特別適合後端開發者、資料工程師，以及需要建置、驗證、部署或操作 Tinybird 專案、又不想憑空猜 flags 或誤用錯誤目標的 agent。

使用者通常在意的問題很單純：我該跑哪個 tb 指令、在哪個環境跑、以及在變更資料或部署之前要先檢查什麼？這個技能就是圍繞這個工作目標設計的。當你需要讓本地開發、Cloud 部署、資料操作、mock data，或 token/secret 處理維持一致時，tinybird-cli-guidelines 最能發揮價值。

為什麼這個技能值得安裝

它的主要價值在於工作流程控管，而不只是幫你找指令。若你希望有一個強調 CLI 4.0 行為、環境目標設定，以及安全操作習慣的技能，tinybird-cli-guidelines install 很有用。它能減少 tb build、tb deploy、破壞性資料變更，以及本地與 Cloud 混用造成的錯誤。

最適合後端開發的情境

當你的工作會碰到 Tinybird datasource、pipe、部署或本地測試時，就使用 tinybird-cli-guidelines for Backend Development。如果你需要一份精簡的 tb CLI 操作指南，尤其是在建置/部署行為取決於 tinybird.config.json 的 repository 中，這個技能很合適。

它不打算做什麼

這不是一般性的 Tinybird 教學，也不是完整的 repo 摘要。它是專為 CLI 使用與操作流程設計的決策輔助技能。如果你只需要一次性的指令解釋，tb <command> --help 可能就夠了；如果你需要可重複執行的工作流程，這個技能就更有價值。

如何使用 tinybird-cli-guidelines 技能

安裝後先確認技能範圍

使用下列指令安裝 tinybird-cli-guidelines：

npx skills add tinybirdco/tinybird-agent-skills --skill tinybird-cli-guidelines

安裝完成後，先讀 SKILL.md，再開啟與你的任務相符的支援規則檔。最有用的檔案包括 rules/cli-commands.md、rules/build-deploy.md、rules/local-development.md 與 rules/data-operations.md。

把模糊需求改寫成可用提示詞

這個技能在提示詞包含以下資訊時效果最好：

• 目標：build、deploy、append、replace、delete 或 test
• 環境：local、branch 或 cloud
• 資產：datasource、pipe、token、secret 或 project file
• 風險等級：safe check、non-destructive 或已確認的 destructive change

更強的提示詞會像這樣：Use tinybird-cli-guidelines to validate a Tinybird project, explain which tb commands to run in CLI 4.0, and avoid destructive deploys unless I confirm.

先讀對應的檔案

先從 SKILL.md 開始，再依任務選擇對應的規則檔：

• rules/build-deploy.md：tb build 與 tb deploy
• rules/data-operations.md：delete / replace / truncate 行為
• rules/append-data.md：附加檔案、URL 或 events
• rules/local-development.md：Tinybird Local 設定與疑難排解
• rules/tokens.md 與 rules/secrets.md：認證與組態工作

用工作流程規則，不要靠記憶

在 tinybird-cli-guidelines usage 中，最有價值的建議是尊重 CLI 4.0 的 context。先在 tinybird.config.json 設定 dev_mode，然後直接使用 tb build 和 tb deploy，除非你真的需要手動覆寫。任何可能變更 production 或刪除資料的指令，在執行前都應先到技能中確認完整語法，或用 tb <command> --help 再核對一次。

tinybird-cli-guidelines 技能 FAQ

tinybird-cli-guidelines 只適合 Tinybird 專家嗎？

不是。它對需要更安全預設值的初學者有幫助，對想減少環境誤用的進階使用者也一樣有用。當你知道業務目標，卻不確定最安全的 Tinybird CLI 路徑時，這個技能特別實用。

這和一般提示詞有什麼不同？

一般提示詞可以描述任務，但 tinybird-cli-guidelines 提供的是可重複使用的操作模型：要先看哪裡、要確認什麼、以及什麼時候該停下來要求批准。這一點對 tb build、tb deploy 和資料變更指令最重要。

什麼情況下不該用這個技能？

如果你不是在處理 Tinybird CLI 指令、Tinybird Local，或 Tinybird 部署流程，就可以跳過它。對於非常簡單、只讀、且不涉及 project files、環境或操作風險的問題，也不需要用它。

它同時涵蓋本地與 Cloud 工作流程嗎？

是的。tinybird-cli-guidelines 指南涵蓋 Tinybird Local、以 branch 為基礎的開發，以及 Cloud 部署。當你需要更少人工判斷，從本地迭代一路推進到 production 時，它就很適合。

如何改進 tinybird-cli-guidelines 技能

直接提供具體操作與目標

你的輸入越精準，輸出就越好。不要只說「幫我處理 Tinybird」，而是說「執行安全的本地 build」、「準備 production deploy 檢查」，或「把 CSV 資料 append 到既有 datasource」。同時提供 datasource 或 project name，並說明目標是 local、branch 還是 cloud。

先把限制說清楚

最常見的失敗原因是風險界線不清楚。如果你不能接受破壞性變更，就要在技能建議 tb deploy --allow-destructive-operations 或 replace 指令之前先講明。若你正在 main 或 master 上操作，也要一起說明，因為 branch mode 的行為不同。

資料操作請提供具體輸入

在使用 tinybird-cli-guidelines usage 處理 append、replace 或 delete 任務時，請提供檔案路徑、列條件、partition key，以及 schema 是否不變。例如：「用 data.csv replace events 的 11 月資料；partition key 是 country；不要影響 active ingestion。」這種細節能避免產生不安全或不完整的指令規劃。

上 production 前先用檢查步驟迭代

在把任何內容推進到 Cloud main 之前，先使用 tb info、tb deploy --check，以及對應的規則檔。如果第一次得到的結果太籠統，就補上指令、環境，以及希望技能檢查的確切檔案，讓回應更貼近你的實際流程。